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1. LINK LINKAGE EDITOR. 

LINK is a utility used to combine relocatable object modules 
into an absolute file ready for execution under CP/M or MP/M. The 
relocatable object modules may be of two types. The first has a 

filetype of REL, and is produced by PL/I-80, RMAC, or any other 
language translator that produces relocatable object modules in the 
Microsoft format. The second has a filetype of IRL, and is generated 
by the CP/M librarian LIB. An IRL file contains the same information 
as a REL file, but includes an index which allows faster linking of 
large libraries. 

Upon completion, LINK lists the symbol table, any unresolved 
symbols, a memory map and the use factor at the console. The memory 
map shows the size and locations of the different segments, and the 
use factor indicates the amount of available memory used by LINK as a 
hexadecimal percentage. LINK writes the symbol table to a SYM file 
suitable for use with the CP/M Symbolic Instruction Debugger (SID) , 
and creates a COM or PRL file for direct execution under CP/M or MP/M. 



1.1. LINK Operation 

LINK is invoked by typing 

LINK filenamel{ , filename 2 , .. . ,filenameN} 

where f ilenamel , . . . ,f ilenameN are the names of the object modules to 
be linked. If no filetype is specified, REL is assumed. LINK will 

produce two files: filenamel.COM and f ilenamel .SYM. If some other 
filename is desired for the COM and SYM files, it may be specified in 
the command line as follows: 

LINK newf ilename=f ilenamel{ , f ilename2, . . . ,f ilenameN} 

When linking PL/I programs, LINK will automatically search the 
run-time library file PLILIB.IRL on the default disk and include any 
subroutines used by the PL/I programs. 

A number of optional switches, provided for additional control 
of the link operation, are described in the following section. 

During the link process, LINK may create up to eight temporary 
files on the default disk. The files are named: 

XXABS. $$$ XXPR0G.$$$ XXDATA.$$$ XXC0MM.$$$ 
YYABS.$$$ YYPR0G.$$$ YYDATA.$$$ YYC0MM.$$$ 

These files are deleted if LINK terminates normally, but may remain on 
the disk if LINK aborts due to an error condition. 



1.2. LINK Switches 

LINK switches are used to control the execution parameters of 
LINK. They are enclosed in square brackets immediately following one 
or more of the filenames in the command line, and are separated by 
c omma s . 

Example: 

LINK TEST[L4000] , IOMOD, TESTLIB [S r NL, GSTART] 

All switches except the S switch may appear after any filename 
in the command line. The S switch must follow the filename to which 
it refers. 



1.2.1. The Additional Memory (A) Switch. The A switch is used 
to provide LINK with additional space for symbol table storage by 
decreasing the size of LINK'S internal buffers. This switch should be 
used only when necessary, as indicated by a MEMORY OVERFLOW error, 
since using it causes the internal buffers to be stored on the disk, 
thus slowing down the linking process considerably. 



1.2.2. The Data Origin (D) Switch. The D switch is used to 
specify the origin of the data and common segments. If not used, LINK 
will put the data and common segments immediately after the program 
segment. The form of the D switch is Dnnnn, where nnnn is the desired 
data origin in hex. 



1.2.3. The Go (G) Switch. The G switch is used to specify the 
label where program execution is to begin, if it does not begin with 
the first byte of the program segment. LINK will put a jump to the 
label at the load address. The form of the G switch is G<label>. 



1.2.4. The Load Address (L) Switch. The load address defines 
the base address of the COM file generated by LINK. Normally, the 
load address is 100H, which is the base of the Transient Program Area 
in a standard CP/M system. The form of the L switch is Lnnnn, where 
nnnn is the desired load address in hex. The L switch also sets the 
program origin to nnnn, unless otherwise defined by the P switch. 



Note that COM files created with a load address other than 100H will 
not execute properly under a standard CP/M system. 



1.2.5. The Memory Size (M) Switch. The M switch may be used 
when creating PRL files for execution under MP/M to indicate that 
additional data space is required by the PRL program for proper 
execution. The form of the M switch is Mnnnn, where nnnn is the 
amount of additional data space needed in hex. 



1.2.6. The No List (NL) Switch. The NL switch is used to 
suppress the listing of the symbol table at the console. 



1.2.7. The No Recording of Symbols (NR) Switch. The NR switch 
is used to suppress the recording of the symbol table file. 



1.2.8. The Output COM File (OC) Switch. The OC switch directs 
LINK to produce a COM file. This is the default condition for LINK. 



1.2.9. The Output PRL File (OP) Switch. The OP switch directs 
LINK to produce a page relocatable PRL file for execution under MP/M, 
rather than a COM file. See section 1.3 for more information on 
creating PRL files. 



1.2.10. The Program Origin (P) Switch. The P switch is used to 
specify the origin of the program segment. If not used, LINK will put 
the program segment at the load address, which is 100H unless 
otherwise specified by the L switch. The form of the P switch is 
Pnnnn, where nnnn is the desired program origin in hex. 



1.2.11. The '?' Symbol (Q) Switch. Symbols in the PL/I 
run-time library begin with a question mark to avoid conflict with 
user symbols. Normally LINK suppresses listing and recording of these 
symbols. The Q switch causes these symbols to be included in the 
symbol table listed at the console and recorded on the disk. 



1.2.12. The Search (S) Switch. The S switch is used to 
indicate that the preceding file should be treated as a library. LINK 
will search the file and include only those modules containing symbols 
which are referenced but not defined in the modules already linked. 



1.3. Creating MP/M PRL Files 

Assembly language programs often contain references to symbols 
in the base page such as BOOT, BDOS, DFCB, and DBUFF. To run properly 
under CP/M (or as a COM file under MP/M) these symbols are simply 
defined in equates as follows: 



BOOT 


EQU 





BDOS 


EQU 


5 


DFCB 


EQU 


5CH 


DBUFF 


EQU 


80H 



;JUMP TO WARM BOOT 
;JUMP TO BDOS ENTRY POINT 
;DEFAULT FILE CONTROL BLOCK 
;DEFAULT I/O BUFFER 



With PRL files f however, the base page itself may be relocated at load 
time, so LINK must know that these symbols, while at fixed locations 
within the base page, are relocatable. To do this, simply declare 
these symbols as externals in the modules in which they are 
referenced: 

EXTRN BOOT, BDOS, DFCB, DBUFF 

and link in another module in which they are declared as publics and 
defined in equates: 



PUBLIC BOOT, BDOS, DFCB, DBUFF 



BOOT 


EQU 





BDOS 


EQU 


5 


DFCB 


EQU 


5CH 


DBUFF 


EQU 
END 


80H 



JUMP TO WARM BOOT 
JUMP TO BDOS ENTRY POINT 
DEFAULT FILE CONTROL BLOCK 
DEFAULT I/O BUFFER 



1.4. Sample Link 

A sample link is shown on the following pages. First the sample 
program GRADE. PLI is compiled, and then a COM file is created by LINK. 
LINK automatically searches the PL/I run-time library PLILIB.IRL for 
the subroutines used by GRADE. The Q switch causes the symbols taken 
from PLILIB.IRL to be included in the symbol table listing (and the 
SYM file) . The memory map following the symbol table indicates the 
length and location assigned to each of the segments. A use factor of 
49 indicates that 49H% r or a little more than a quarter of the memory 
available to LINK was used. 



PL/I-80 VI. 0', COMPILATION OF: GRADE 

D: Disk Print 

L: List Source Program 

NO ERROR(S) IN PASS 1 

NO ERROR(S) IN PASS 2 



PL/I-80 VI. 0, COMPILATION OF: GRADE 



1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 



000 ave 

0006 

0006 

0006 

0006 

000D 

00D 

000D 

00D 

0014 

0014 

0017 

0033 

0044 

0047 

0047 

0047 

004F 

0052 

005B 

008A 

08A 

08D 

008D 

008D 

00A9 

00A9 

00AF 

00B9 

00B9 

00B9 

0CA 

00CA 

00E2 

00ED 

00F7 

00F7 



rage: 
proc options (main); 
/'* grade averaging program */ 



del 



sysin file, 

(grade, total, n) fixed; 



on error (1) 

/* conversion */ 

begin; 

put skip list(*Bad Value, Try Again.'); 

get skip; 

go to retry; 

end; 

on endfile (sysin) 
begin; 
if n ~= then 

put skip list 

('Average is' ,total/n) ; 
stop; 
end; 

put skip list 

('Type a List of Grades, End with Ctl-Z'); 
total = 0; 
n = 0; 

retry: 
put skip; 

do while('l'b) ; 

get list (grade) ; 

total = total + grade; 

n = n + 1; 

end; 
end average; 



CODE SIZE = 00F7 
DATA AREA = 004C 



B>link g 


rade[q] 














LINK V0.< 
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AVE RAG 


0100 


/SYSIN/ 


1B77 


7START 


1A08 


70NC0P 


18AE 


7SYSPR 


02C5 


7SKPOP 


0430 


7SLCTS 


1367 


7PNC0P 


01FD 


?QIOOP 


1987 


7SYSIN 


02C1 


7ID2 2N 


13B3 


7QIC0P 


127E 


7PNV0P 


0221 


7STOPX 


1B19 


7RECOV 


1468 


7GNV0P 


07D5 


7QCI0P 


11FB 


/7FILAT/ 


1B9C 


/7FPB/ 


1BA5 


7PNB0P 


01F7 


7PNCPR 


04CF 


7IS22N 


13F9 


7SIOOP 


02CA 


7SI0PR 


02E8 


/7FPBST/ 


1BD3 


/SYSPRI/ 


1BE6 


70IOOP 


05A7 


7FPBI0 


0758 


70I0PR 


05C6 


7BSL16 


131C 


7SIGNA 


1626 


7SKPPR 


0439 


7GNCPR 


094F 


7WRBYT 


0E36 


7 PAG OP 


07C7 


7NST0P 


1322 


7SMVCW 


1390 


7SJSVM 


132D 


7SSCFS 


137A 


7QB08I 


11E7 


70PNFI 


0D13 


/7FMTS/ 


1C0E 


7FPBOU 


19DB 


7FPBIN 


1993 


7GNVPR 


0812 


7RDBYT 


0E23 


7RDBUF 


0E5C 


7WRBUF 


0E7F 


7CL0SE 


0F68 


7GETKY 


0F99 


7SETKY 


0FBF 


7 PATH 


0F4C 


7BD0S 


0005 


7DFCB0 


005C 


7DFCB1 


006C 


7DBUFF 


0080 


7ALL0P 


14D2 


7FREOP 


1568 


7 ADD 10 


1A64 


7SUBI0 


1A7B 


7WRCHR 


19F1 


7RFSIZ 


10C4 


7RRFCB 


1136 


7RWFCB 


113B 


7QB16I 


11EA 


7IN20 


13F1 


7CNVER 


1400 


7BSL08 


1316 


7SJSCM 


132F 


7SJSTS 


1341 


7SLVTS 


1365 


7SMCCM 


1394 


7ID22 


13CB 


7IN20N 


13F1 


7ZER0D 


1420 


7IS22 


13F9 


/7C0NSP/ 


1C16 


70FCOP 


14B2 


7RSBLK 


1437 


7RECLS 


1E79 


7ERMSG 


1B34 


7BEGIN 


1E77 


/70NC0D/ 


1C37 


7SIG0P 


1616 


7 STACK 


1E71 


70NCPC 


194B 


7REV0P 


1903 


/7CNC0L/ 


1C3A 


7B00T 


0000 


7CNIEW 


1B77 


7DMEM 


1E7B 






ABSOLUTE 


0000 












CODE SIZE 1A77 (0100- 


1B76) 










DATA SIZE 023F (1C3C- 


1E7A) 










COMMON SIZE 00C5 (1B77- 


1C3B) 










USE FACTOR 


49 













A>b:grade 

Type a List of Grades, End with Ctl-Z 

50, 75, 25 

~Z 

Average is 50 
End of Execution 



A>b:grade 

Type a List of Grades, End with Ctl-Z 

50 

75 

zot,66 

Bad Value, Try Again. 

25 

"Z 

Average is 50 
End of Execution 



A>b:grade 

Type a List of Grades, End with Ctl-Z 
~Z 

End of Execution 
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1.5. Error Messages 

CANNOT CLOSE: An output file cannot be closed. The diskette may be 
write protected. 

COMMON ERROR: An undefined common block has been selected. 

DIRECTORY FULL: There is no directory space for the output files or 
intermediate files. 

DISK READ ERROR: A file cannot be read properly. 

DISK WRITE ERROR: A file cannot be written properly, probably due to 
a full diskette. 

FILE NAME ERROR: The form of a source file name is invalid. 

FIRST COMMON NOT LARGEST: A subsequent COMMON declaration is larger 
than the first COMMON declaration for the indicated block. 
Check that the files being linked are in the proper order, or 
that the modules in a library are in the proper order. 

INDEX ERROR: The index of an IRL file contains invalid information. 

INSUFFICIENT MEMORY: There is not enough memory for LINK to allocate 
its buffers. Try using the A switch. 

INVALID REL FILE: The file indicated contains an invalid bit pattern. 
Make sure that a REL or IRL file has been specified. 

INVALID SYNTAX: The command line used to invoke LINK was not properly 
formed. 

MAIN MODULE ERROR: A second main module was encountered. 

MEMORY OVERFLOW: There is not enough memory to complete the link 
operation. Try using the A switch. 

MULTIPLE DEFINITION: The specified symbol is defined in more than one 
of the modules being linked. 

NO FILE: The indicated file cannot be found. 

OVERLAPPING SEGMENTS: LINK attempted to write a segment into memory 
already used by another segment. Probably caused by incorrect 
use of P and/or D switches. 

UNDEFINED START SYMBOL: The symbol specified with the G switch is not 
defined in any of the modules being linked. 

UNDEFINED SYMBOLS: The symbols following this message are referenced 
but not defined in any of the modules being linked. 

UNRECOGNIZED ITEM: An unfamiliar bit pattern has been scanned (and 
ignored) by LINK. 



1.6. Format of REL Files 

The information in a REL file is encoded in a bit stream, which 
is interpreted as follows: 

1) If the first bit is a 0, then the next 8 bits are loaded 
according to the value of the location counter. 

2) If the .first bit is a 1, then the next 2 bits are interpreted as 
follows: 

00 - special link item (see 3) 

01 - program relative. The next 16 bits are loaded after being 

offset by the program segment origin. 

10 - data relative. The next 16 bits are loaded after being 

offset by the data segment origin. 

11 - common relative. The next 16 bits are loaded after being 

offset by the origin of the currently selected common 
block. 

3) A special item consists of: 

- A 4 bit control field which selects one of 16 special link 
items described below. 

- An optional value field which consists of a 2 bit address type 
field and a 16 bit address field. The address type field is 
interpreted as follows: 

00 - absolute 

01 - program relative 

10 - data relative 

11 - common relative 

- An optional name field which consists of a 3 bit name count 
followed by the name in 8 bit ASCII characters. 

The following items are followed by a name field only. 

0000 - entry symbol. The symbol indicated in the name field is 

defined in this module, so the module should be linked if 
the current file is being searched (as indicated by the S 
switch) . 

0001 - select common block. Instructs LINK to use the location 

counter associated with the common block indicated in the 
name field for subsequent common relative items. 
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0010 - program name. The name of the relocatable module. LINK 

checks that the first item in each module if a program 
name, and issues an error if it is not. 

0011 - unused. 

0100 - unused. 

The following items are followed by a value field and a name field. 

0101 - define common size. The value field determines the 

amount of memory to be reserved for the common block 
described in the name field. The first size allocated to 
a given block must be larger than or equal to any 
subsequent definitions for that block in other modules 
being linked. 

0110 - chain external. The value field contains the head of a 

chain which ends with an absolute 0. Each element of the 
chain is to be replaced with the value of the external 
symbol described in the name field. 

0111 - define entry point. The value of the symbol in the name 

field is defined by the value field. 

1000 - unused. 

The following items are followed by a value field only. 

1001 - external plus offset. The following two bytes in the 

current segment must be offset by the value of the value 
field after all chains have been processed. 

1010 - define data size. The value field contains number of 

bytes in the data segment of the current module. 

1011 - set location counter. Set the location counter to the 

value determined by the value field. 

1100 - chain address. The value field contains the head of a 

chain which ends with an absolute 0. Each element of the 
chain is to be replaced with the current value of the 
location counter. 

1101 - define program size. The value field contains the number 

of bytes in the program segment of the current module. 

1110 - end module. Defines the end of the current module. If 
the value field contains a value other than absolute f 
it is to be used as the start address for the program 
being linked. The next item in the file will start at 
the next byte boundary. 

The following item has no value field or name field. 
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1111 - end file. Follows the end module item of the last module 
in the f ile. 



1.7. Format of IRL Files 

An IRL file consists of three parts: a header, an index and a 
REL section. 

The header contains 128 bytes defined as follows: 

byte - extent number of first record of REL section, 
byte 1 - record number of first record of REL section, 
bytes 2-127 - currently unused. 

The index Consists of a number of entries corresponding to the 
entry symbol items in the REL section. The entries are of the form: 

I I I I I I III 

I e | r I b | cl | c2 I ... I en I d I 
I I I I I I I I I 

where: 

e = extent offset from start of REL section to start of module 

r = record offset from start of extent to start of module 

b = byte offset from start of record to start of module 

cl-cn = name of symbol 

d = end of symbol delimiter (0FEH) 

The index is terminated by an entry in which cl = 0FFH. The remainder 
of the record containing the terminating entry is unused. 

The REL section contains the relocatable object code as 
described in the previous section. 
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2. RMAC RELOCATING MACRO ASSEMBLER. 

The CP/M Relocating Macro Assembler, called RMAC, is a modified 
version of the CP/M Macro Assembler (MAC). RMAC produces a 
relocatable object file (REL) , rather than an absolute object file 
(HEX) , which may be linked with other modules produced by RMAC, or 
other language translators such as PL/I-80, to produce an absolute 
file ready for execution. 

The differences between RMAC and MAC are described in the 
following sections. For a complete description of the assembly 
language and macro facilities, see CP/M MAC Macro Assembler: Language 
Manual and Application Guide. 



2.1. RMAC Operation 

RMAC is invoked by typing 

RMAC f ilename. f iletype 

followed by optional assembly parameters. If the f iletype is not 
specified, ASM is assumed. RMAC produces three files: a list file 
(PRN) , a symbol file (SYM) , and a relocatable object file (REL) . 
Characters entered in the source file in lower case appear in lower 
case in the list file, except for macro expansions. 

The assembly parameter "H" in MAC, used to control the 
destination of the HEX file, has been replaced by "R", which controls 
the destination of the REL file. Directing the REL file to the 
console or printer (RX or RP) is not allowed, since the REL file does 
not contain ASCII characters. 

Example: 

RMAC TEST $PX SB RB 

directs RMAC to assemble the file TEST. ASM, send the PRN file to the 
console, and put the symbol file (SYM) and the relocatable object file 
(REL) on dr ive B. 



2.2. Expressions 

The operand field of a statement may consist of a complex 
arithmetic expression (as described in the MAC manual, section 3) with 
the following restrictions: 

1) In the expression A+B , if A evaluates to a relocatable value or 
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2) 
3) 



an external, then B must be a constant. 

In the expression A-B, if A is an external, then B must be a 
constant. 

In the expression A-B, if A evaluates to a relocatable value, 
then: 



a) 



B must be a constant, or 



4) 



b) B must be a relocatable value of the same relocation type 
as A (both must appear in a CSEG, DSEG, or in the same 
COMMON block) . 

In all other arithmetic and logical operations, both operands 
must be absolute. 



An expression error ('E') will be generated if an expression 
does not follow the above restrictions. 



2.3. Assembler Directives 

The following assembler directives have been added to support 
relocation and linking of modules: 

ASEG use absolute location counter 

CSEG use code location counter 

DSEG use data location counter 

COMMON use common location counter 

PUBLIC symbol may be referenced in another module 

EXTRN symbol is defined in another module 

NAME name of module 

The directives ASEG, CSEG, DSEG and COMMON allow program modules 
to be split into absolute, code, data and common segments, which may 
be rearranged in memory as needed at link time. The PUBLIC and EXTRN 
directives provide for symbolic references between program modules. 

NOTE: While symbol names may be up to 16 characters, the first 
six characters of all symbols in PUBLIC, EXTRN and COMMON statements 
must be unique, since symbols are truncated to six characters in the 
object module. 
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2.3.1. The ASEG Directive. The ASEG statement takes the form 

label ASEG 

and instructs the assembler to use the absolute location counter until 
otherwise directed. The physical memory locations of statements 
following an ASEG are determined at assembly time by the absolute 
location counter, which defaults to and may be reset to another 
value by an ORG statement following the ASEG statement. 



2.3.2. The CSEG Directive. The CSEG statement takes the form 

label CSEG 

and instructs the assembler to use the code location counter until 
otherwise directed. This is the default condition when RMAC begins an 
assembly. The physical memory locations of statements following a 
CSEG are determined at link time. 



2.3.3. The DSEG Directive. The DSEG statement takes the form 

label DSEG 

and instructs the assembler to use the data location counter until 
otherwise directed. The physical memory locations of statements 
following a DSEG are determined at link time. 



2.3.4. The COMMON Directive. The COMMON statement takes the 
form 

COMMON /identifier/ 

and instructs the assembler to use the COMMON location counter until 
otherwise directed. The physical memory locations of statements 
following a COMMON statement are determined at link time. 



2.3.5. The PUBLIC Directive. The PUBLIC statement takes the 
form 
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PUBLIC label{ , label, . ... , label} 

where each label is defined in the program. Labels appearing in a 
PUBLIC statement may be referred to by other programs which are linked 
using LINK-80. 



2.3.6. The EXTRN Directive. The form of the EXTRN statement is 

EXTRN label{ , label,. .. ,label} 

The labels appearing in an EXTRN statement may be referenced but must 
not be defined in the program being assembled. They refer to labels 
in other programs which have been declared PUBLIC. 



2.3.7. The NAME Directive. The form of the NAME statement is 

NAME 'text string" 

The NAME statement is optional. It is used to specify the name of the 
relocatable object module produced by RMAC. If no NAME statement 

appears, the filename of the source file is used as the name of the 
object module. 
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3. LIB PROGRAM LIBRARIAN. 

The function of LIB is to handle libraries, which are files 
consisting of any number of relocatable object modules. LIB can 
concatenate a group of REL files into a library, create an indexed 
library (IRL) , select modules from a library, and print module names 
and PUBLICS from a library. 



3.1. LIB Operation 

LIB is invoked by typing 

LIB f ilename=f il enamel , . . . ,f ilenameN 

This command will create a library called filename. REL from the files 
f ilenamel. REL, ... ,f ilenameN. REL. If filetypes are omitted, REL is 
assumed . 

A filename may be followed by a group of module names enclosed 
in parentheses. Only the modules indicated will be included in the 

LIB function being performed. If omitted, all modules in the file are 
included. 

Example : 

LIB TEST=A(A1,A2) ,B,C(C1-C4,C6) 

This command will create a file TEST. R 1 EL cbh&isting of modules Al and 
A2 from A. REL, all the modules from B.REL, and the modules between CI 
and C4, and C6 from C.REL. 

Any of several optional switches may be included in the command 
line for LIB. These switches are enclosed in square brackets and 

appear after the first filename in the LIB command. The switches are: 

I - create an indexed library (IRL) 

M - print module names 

P - print module names and PUBLICS 
Examples: 

LIB TEST=A,B,C 
creates a file TEST. REL consisting of A. REL, B.REL and C.REL. 

LIB TEST=TEST,D 
appends D.REL to the end of TEST. REL. 
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LIB TEST[I] 

creates an indexed library TEST. IRL from TEST.REL. 

LIB TEST[I]=A,B,C,D 

performs the same function as the preceding LIB examples, except no 
TEST.REL file is created. 

LIB TEST[P] 

lists all the module names and PUBLICS in TEST.REL. 



3.2. Error Messages 

CANNOT CLOSE: The output file cannot be closed. The diskette may be 
write protected. 

DIRECTORY FULL: There is no directory space for the output file. 

DISK READ ERROR: A file cannot be read properly. 

DISK WRITE ERROR: A file cannot be written properly, probably due to 
a full diskette. 

FILE NAME ERROR: The form of a source file name is invalid. 

NO FILE: The indicated file cannot be found. 

NO MODULE: The indicated module cannot be found. 

SYNTAX ERROR: The command line used to invoke LIB was not properly 
formed. 
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4 . DATA REPRESENTATION AND INTERFACE CONVENTIONS. 

This section describes the layout of memory used by various 
Digital Research language processors so that the programmer can 
properly interface assembly language routines with high level language 
programs and the PL/I-80 runtime subroutine library. A set of 
standard subroutine interface conventions is also given so that 
programs produced by various programmers and language processors can 
be conveniently interfaced. 



below. 



4.1. Representation of Data Elements. 

The internal memory representation of data items is presented 



4.1.1. Pointers, and Entry and Label Variables. Variables 
which provide access to memory addresses are stored as two contiguous 
bytes, with the low order byte stored first in memory. Pointer, 
Entry, and Label data items appear graphically as shown below: 



I LSI MS I 



where "LS" denotes the least significant half of the address, and "MS" 
denotes the most significant portion. Note that MS is the "page 
address," where each memory page is 256 bytes, and LS is the address 
within the page. 



4.1.2. Fixed Binary Data Format. Simple single and double byte 
signed integer values are stored in Fixed Binary format. Two modes 
are used, depending upon the precision of the data item. Fixed Binary 
values with precision 1-7 are stored as single byte values, while data 
items with precision 8-15 are stored in a word (double byte) location. 
As with other 8080, 8085, and Z-80 items, the least significant byte 
of multi-byte storage appears first in memory. All Fixed Binary data 
is represented in two's complement form, allowing single byte values 
in the range -128 to +127, and word values in the range -32768 to 
+32767. The values 0, 1, and -1 are shown graphically below, where 
each boxed value represents a byte of memory, with the low order byte 
appearing before the high order byte: 

Fixed Binary(7) Fixed Binary(15) 

1001 I 00 I 00 I 
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Fixed Binary(7) Fixed Binary(15) 
1011 1 01 1 00 I 



Fixed Binary(7) Fixed Binary(15) 
|FE| |FE|FF| 



4.1.3. Bit Data Representation. Bit String data, like the 
Fixed Binary items shown above, are represented in two forms, 
depending upon the declared precision. Bit Strings of length 1-8 are 
stored in a single byte, while Bit Strings of length 9-16 occupy a 
word (double byte) value. Bit values are left justified in the word, 
with "don't care" bits to the right when the precision is not exactly 
8 or 16 bits. The least significant byte of a word value is stored 
first in memory. The Bit String constant values 'l'b, 'A0'b4, and 
'1234' b4 are stored as shown below 

Bit(16) 

100 1 30 | 



Bit(8) 


1801 


Bit:(8) 


|A0| 


Bit(8) 


N/A 



Bit(16) 
|00|A0| 



Bit(16) 
I 34 1 12 I 



4.1.4. Character Data Representation. Two forms of character 
data are stored in memory, depending upon the declaration. Fixed 
character strings, declared as CHAR(n) without the VARYING attribute, 
occupy n contiguous bytes of storage with the first string character 
stored lowest in memory. Character strings declared with the VARYING 
attribute are prefixed by the character string length, ranging from 
to 254. The length of the area reserved for a CHAR(n) VARYING is n+1 . 
Note that in either case, n cannot exceed 254. The string constant 

•Walla walla Wash' 
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is stored in a CHAR(20) fixed character string as 

iWlalllllal IWlalllllal |W|a|s|hl I I I I 

This same string is stored in a CHAR(20) VARYING data area as 

|10|W|a|l|l|a| IWlalllllal I W| a| s| hi ? I ?l ? I ? I 

where "10" is the (hexadecimal) string length, and "?" represents 
undefined character positions. 



4.1.5. Fixed Decimal Data Representation. Decimal data items 
are stored in packed BCD form, using nine's complement data 
representation. The least significant BCD pair is stored first in 
memory, with one BCD digit position reserved for the sign. Positive 
numbers have a sign, while negative numbers have a 9 in the high 
order sign digit position. The number of bytes occupied by a decimal 
number depends upon its declared precision. Given a decimal number 
with precision p, the number of bytes reserved is the integer part of 

(P + 2) / 2 

where p varies between 1 and 15, resulting in a minimum of 1 byte and 
a maximum of 8 bytes to hold a decimal data item. Given a decimal 
number field of precision 5, the numbers 12345 and -2 are represented 
as shown below 



1451 23 1011 198199199 



4.1.6. Floating Point Binary Representation. Floating Point 
Binary numbers are stored in four consecutive byte locations, no 
matter what the declared precision. The number is stored with a 24 
bit mantissa, which appears first in memory, followed by an 8-bit 
exponent. Following data storage conventions, the least significant 
byte of the mantissa is stored first in memory. The floating point 
number is normalized so that the most significant bit of the mantissa 
is "1" for non-zero numbers. A zero mantissa is represented by an 
exponent byte of 00. Since the most significant bit of the mantissa 
must be "1" for non-zero values, this bit position is replaced by the 
mantissa sign. The binary exponent byte is biased by 80 (hexadecimal) 
so that 81 represents an exponent of 1 while 7F represents an exponent 
of -1. The Floating Point Binary value 1.5 has the representation 
shown below 
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00100140181! 

Note that in this case, the mantissa takes the bit stream form 

0100 0000 0000 0000 0000 0000 

which indicates that the mantissa sign is positive. Setting the 

(assumed) high order bit to "1" produces the mantissa bit stream 

1100 0000 0000 0000 0000 121000 

Since the exponent 81 has a bias of 80, the binary exponent is 1, 
resulting in the binary value 

1.100 0000 0000 0000 0000 0000 

or, equivalently , 1.5 in a decimal base. 



4.1.7. File Constant Representation. Each file constant in a 
PL/I-80 program occupies 32 contiguous bytes, followed by a variable 
length field of to 14 additional bytes. The fields of a file 

constant are all implementation dependent and subject to change 
without notice. 



4.2. Layout of Aggregate Storage. 

PL/I-80 data items are contiguous in memory with no filler 
bytes. Bit data is always stored unaligned. Arrays are stored in 

row-major order, with the first subscript running slowest and the last 
subscript running fastest. The RMAC COMMON statement is used to share 
data with PL/I-80 programs which declare data using the EXTERNAL 
attribute. The following PL/I-80 program is used as an example: 

declare 

a (10) bit(8) external, 
1 b external, 

2 c bit(8) , 

2 d fixed binary(15) , 

2 e (0:2,0:1) fixed; 

The following RMAC COMMON areas share data areas with the program 
containing the declaration given above. 
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common 


/a/ 


x: 


ds 


1 




common 


/b/ 


c: 


ds 


1 


d: 


ds 


2 


e00: 


ds 


2 


e01: 


ds 


2 


el0: 


ds 


2 


ell: 


ds 


2 


e20: 


ds 


2 


e21: 


ds 


2 



where the labels e00 r e01, . .., e21 correspond to the PL/I-80 
subscr ipted var iable locations e (0 ,0) , e (0,1) , • • • * e(2,l). 



4.3. General Parameter Passing Conventions. 

Communication between high-level and assembly language routines 
can be performed using the PL/I-80 general-purpose parameter passing 
mechanism described below. Specifically, upon entry to a PL/I-80 or 
assembly language routine, the HL register pair gives the address of a 
vector of pointer values which, in turn, lead the the actual parameter 
values. This situation is illustrated in the diagram below, where the 
address fields are assumed as shown for this example: 



H L 



Parm Address 



Actual Parameters 



1000 



1000:1 2000 I 2000:1 parameter #1 I 
I 3000 I 3000:1 parameter #2 
I 4000 I 4000:1 parameter #3 1 



I 5000 I 5000:1 last parameter I 



The number of parameters, and the parameter length and type is 
determined implicitly by agreement between the calling program and 
called subroutine. 

Consider the following situation, for example. Suppose a 

PL/I-80 program uses a considerable number of floating point divide 
operations, where each division is by a power of two. Suppose also 

that the loop where the divisions occur is speed-critical, and thus an 
assembly language subroutine will be used to perform the division. 
The assembly language routine will simply decrement the binary 
exponent for the floating point number for each power of two in the 
division, effectively performing the divide operations without the 
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overhead of unpacking, performing the general division operation, and 
repacking the result. During the division, however, the assembly 
language routine could produce underflow. Thus, the assembly language 
routine will have to signal the UNDERFLOW condition if this occurs. 

The programs which perform this function are given on the 
following pages. The DTEST program, listed first, tests the division 
operation. The external entry DIV2 is the assembly language 
subroutine that performs the division, and is defined on line 4 with 
two parameters: a fixed(7) and a floating point binary value. The 
test value 100 is stored into "f" on each loop at line 9, and is 
passed to the DIV2 subroutine on line 10. Each time DIV2 is called, 
the value of f is changed to f/(2**i) and printed using a PUT 
statement. At the point of call, DIV2 receives a list of two 
addresses, corresponding to the two parameters i and f, used in the 
computation. 

The assembly language subroutine, called DIV2, is listed next. 
Upon entry, the value of i is loaded to the accumulator, and the HL 
pair is set to point to the exponent field of the input floating point 
number. If the exponent is zero, DIV2 returns immediately since the 
resulting value is zero. Otherwise, the subroutine loops at the label 
"dby2" while counting down the exponent as the power of two diminishes 
to zero. If the exponent reaches zero during this counting process, 
an UNDERFLOW signal is raised. 

The call to "?signal" within DIV2 demonstrates the assembly 
language set-up for parameters which use the general-purpose 
interface. The ?signal subroutine is a part of the PL/I-80 subroutine 
library (PLILIB.IRL) . The HL register pair is set to the signal 
parameter list, denoted by "siglst. " The signal parameter list, in 
turn, is a vector of four addresses which lead to the signal code 
"sigcode," the signal subcode "sigsub," the file name indicator 
"sigfil" (not used here), and the auxiliary message "sigaux" which is 
the last parameter. The auxiliary message is used to provide 
additional information to the operator when the error takes place. 
The signal subroutine prints the message until either the string 
length is exhausted (32, in this case) or a binary 00 is encountered 
in the string. 

The (abbreviated) output from this test program is shown 
following the assembly language listing. Note that the loop counter i 
becomes negative when it reaches 128, but the processing within the 
DIV2 subroutine treats this value as an unsigned magnitude value, thus 
the underflow occurs when i reaches -123. 



4.4. Returning Values from Functions. 

As an alternative to returning values through the parameter 

list, as described in the previous section, subroutines can produce 

function values which are returned directly in the registers or on the 
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PL/I -80 VI. 0, COMPILATION OF: DTEST 

L: List Source Program 
NO ERROR(S) IN PASS 1 
NO ERROR(S) IN PASS 2 

PL/I-80 VI. f COMPILATION OF: DTEST 

1 a 0000 dtest: 

2 a 0006 proc options(main) ; 

3 c 0006 del 

4 c 0006 div2 entry (fixed(7) , float) , 

5 c 0006 i f ixed(7) , 

6 c 0006 f float; 

7 c 0006 

8 c 0006 do i = by 1; 

9 c 000A f = 100; 

10 c 0015 call div2(i r f) ; 

11 c 001B put skip list(*100 / 2 **',i, '=' ,f ) ; 

12 c 0063 end; 

13 a 0063 end dtest; 

CODE SIZE = 0063 
DATA AREA = 0018 
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0000 
0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 



0009 
000A 
000B 
000C 
000D 
000E 

000F 
0010 
0011 
0012 
0013 



0016 
0019 
001C 



0000 
0002 
0004 
0006 

0008 
0009 
000A 
000C 
000E 
002A 



div2 



5E 
23 
56 
23 
1A 
5E 
23 
56 
EB 



23 
23 
23 
34 
35 
C8 

B7 
C8 
3D 
35 
C20F00 



210000 
CD0000 
C9 



0800 
0900 
0A00 
0C00 

03 

80 

0000 

0E00 

20556E6 



public 

extrn 

entry: 

exit: 



mov 

inx 

mov 

inx 

Id ax 

mov 

inx 

mov 

xchg 



div2 
?signal 

pi -> fixed(7) power of two 
p2 -> floating point number 



Pi 
P2 



-> 
-> 



e ,m 
h 

d ,m 
h 
d 

e,m 
h 
d f m 



(unchanged) 
p2 / (2**pl) 

HL = .low (.pi) 

low( .pi) 

HL = .high(.pl) 

DE = .pi 

HL = ,low(p2) 

a = pi (power of 
;low(.p2) 
;HL = .high( .p2) 
rDE = .p2 
:HL = .p2 



two) 



A = power of 2, 



dby2 



inx 

inx 

inx 

inr 

dcr 

rz 

; divide 

ora 

rz 

dcr 

dcr 

jnz 



h 
h 
h 
m 
m 

by 
a 



two 



a 
m 
dby2 



HL = .low byte of fp num 
; to middle of mantissa 
; to high byte of mantissa 
; to exponent byte 

; p2 already zero? 
; return if so 

; counted power of 2 to zero? 

; re turn if so 

; count power of two down 

; count exponent down 

; loop again if no underflow 



;underflow occurred, signal underflow condition 
lxi h f siglst;signal parameter list 

call ?signal ; signal underflow 

ret ;normally, no return 



dseg 
siglst: dw 

dw 

dw 

dw 
; end of parameter vector, start of params 

db 

db 

dw 

dw 

db 

end 



sigcod: 
sigsub: 
sigf il : 
sigaux : 
465undmsg: 



sigcod 
s igsub 
sigf il 
sigaux 



3 
128 
0000 
undmso 



;address of signal code 
;address of subcode 
;address of file code 
;address of aux message 



03 = underflow 
arbitrary subcode for id 
no associated file name 
0000 if no aux message 



32 ,' Underflow in Divide by Two * ,0 
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A>b 


:dtest 








100 


/ 


2 


** 





- 


1.000000E+02 


100 


/ 


2 


** 


1 


= 


5.000000E+01 


100 


/ 


2 


** 


2 


= 


2.500000E+01 


100 


/ 


2 


** 


3 


S5 


1.250000E+01 


100 


/ 


2 


** 


4 


= 


0.625000E+01 


100 


/ 


2 


** 


5 


= 


3.125000E+00 


100 


/ 


2 


• * 


6 


= 


1.562500E+00 


100 


/ 


2 


** 


7 


= 


0.781250E+00 


100 


/ 


2 


** 


8 


= 


3.906250E-01 


100 


/ 


2 


** 


9 


= 


1.953125E-01 


100 


/ 


2 


** 


10 


= 


0.976562E-01 


100 


/ 


2 


** 


11 


= 


4.882812E-02 


100 


/ 


2 


** 


12 


55 


2.441406E-02 


100 


/ 


2 


** 


13 


- 


1.220703E-02 


100 


/ 


2 


** 


14 


- 


0.610351E-02 


100 


/ 


2 


** 


15 


55 


3.051757E-03 


100 


/ 


2 


** 


16 


55 


1.525878E-03 


100 


/ 


2 


** 


17 


=5 


0.762939E-03 


100 


/ 


2 


** 


18 


=5 


3.814697E-04 


100 


/ 


2 


** 


19 


= 


1.907348E-04 


100 


/ 


2 


** 


20 


55 


0.953674E-04 


100 


/ 


2 


** 


21 


55 


4.768371E-0 C 


100 


/ 


2 


** 


22 


55 


2.384185 p j 


100 


/ 


2 


** 


23 


55 


1.192^ .a- 30 


100 


/ 


2 


** 


24 


=5 


" ..487E-31 


100 


/ 


2 


** 


25 


= 


.540743E-31 


100 


/ 


2 


** 


? r 




0.770372E-31 


100 


/ 


2 


** 


a.1 


55 


3.851859E-32 


100 


/ 


2 


** 


112 


55 


1.925929E-32 


100 


/ 


2 




113 


55 


0.962964E-32 


100 




^ 


** 


114 


55 


4.814824E-33 


l ■ 


/ 


2 


** 


115 


55 


2.407412E-33 


100 


/ 


2 


** 


116 


=5 


1.203706E-33 


100 


/ 


2 


** 


117 


5= 


0.601853E-33 


100 


/ 


2 


** 


118 


= 


3.009265E-34 


100 


/ 


2 


** 


119 


=5 


1.504632E-34 


100 


/ 


2 


** 


120 


55 


0.752316E-34 


100 


/ 


2 


4c* 


121 


=5 


3.761581E-35 


100 


/ 


2 


** 


122 


5= 


1.880790E-35 


100 


/ 


2 


** 


123 


5= 


0.940395E-35 


100 


/ 


2 


** 


124 


= 


4.701977E-36 


100 


/ 


2 


*• 


125 


55 


2.350988E-36 


100 


/ 


2 


** 


126 


55 


1.175494E-36 


100 


/ 


2 


** 


127 


55 


0.587747E-36 


100 


/ 


2 


** 


-128 


=5 


2.938735E-37 


100 


/ 


2 


** 


-127 


= 


1.469367E-37 


100 


/ 


2 


** 


-126 


55 


0.734683E-37 


100 


/ 


2 


** 


-125 


= 


3.673419E-38 


100 


/ 


2 


** 


-124 


5= 


1.836709E-38 


100 


/ 


2 


** 


-123 


55 


0.918354E-38 


100 


/ 


2 


** 


-122 


55 


4.591774E-39 


UNDERFLOW (128 


) , Unde 


rflow in Divide 



Traceback: 017F 011B 
End of Execution 
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by Two 



stack. This section shows the general-purpose conventions for 
returning data as functional values. 



4.4.1. Returning Pointer, Entry, and Label Variables. 
Variables which provide access to memory addresses occupy a word 
value, as described in the previous section. In the case of Pointer, 
Entry, and Label Variables, the values are returned in the HL register 
pair. If a label variable is returned which can be the target of a GO 
TO operation, it is the responsibility of the subroutine containing 
the label to restore the stack to the proper level when control 
reaches the label. 



4.4.2. Returning Fixed Binary Data. Functions which return 
Fixed Binary data items do so by leaving the result in the A register, 
or HL register pair, depending upon the precision of the data item. 
Fixed Binary data with precision 1-7 are returned in A, while 
precision 8-15 items are returned in HL. It is always safe to return 
the value in HL, with the low order byte copied to the A register, so 
that register A is equal to register L upon return. 



4.4.3. Returning Bit String Data. Similar to Fixed Binary data 
items, Bit String data is returned in the A register, or the HL 
register pair, depending upon the precision of the data item. Bit 
Strings of length 1-8 are returned in A, while precision 9-16 items 
are returned in the HL pair. Note that Bit Strings are left justified 
in their fields, so the BIT(l) value "true" is returned in the A 
register as 80 (hexadecimal). Again, it is safe to return a bit value 
in the HL register pair, with a copy of the high order byte in A, so 
that register A is equal to register H upon return. 



4.4.4. Returning Character Data. Character data items are 
returned on the stack, with the length of the string in register A, 
regardless of whether the function has the VARYING attribute. The 
s t r i ng 

•Walla Walla Wash' 

for example, is returned as shown in the diagram below: 
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A |10| | W| a| 1 | 1 | a| IWlalllllal |W|a|s|h| (low stack) 

SP 

where register A contains the string length 10 (hexadecimal) , and the 
Stack Pointer (SP) addresses the first character in the string. 



4.4.5. Returning Fixed Decimal Data. Fixed Decimal data is 
always returned as a sixteen decimal digit value (8 contiguous bytes) 
in the stack. The low order decimal pair is stored lowest in memory 
(at the "top" of the stack) , with the high order digit pair highest in 
memory. The number is represented in nine's complement form, and 
sign-extended through the high order digit position, with a positive 
sign denoted by 0, and a negative sign denoted by 9. The decimal 
number -2, for example, is returned as shown below: 



|98|99|99|99|99|99|99|99| (low stack) 



SP 



4.4.6. Returning Floating Point Numbers. Floating Point 
numbers are returned as a four-byte sequence at the top of the stack, 
regardless of the declared precision. The low order byte of the 
mantissa is at the top of the stack, followed by the middle byte, then 
the high byte. The fourth byte is the exponent of the number. The 
value 1.5 is returned as shown in the following diagram: 



00100140(81 I (low stack) 



SP 



The sequence 



POP D 
POP B 



loads the Floating Point value from the stack for manipulation, 
leaving the exponent in B, and the 24-bit mantissa in C, D, and E. 
The result can be placed back into the stack using 
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PUSH B 
PUSH D 

An example of returning a functional value is shown in the two 
program listings which follow. The first program, called FDTEST, is 
similar to the previous floating point divide test, but instead 
includes an entry definition for FDIV2 which is an assembly language 
subroutine that returns the result in the stack. The FDIV2 subroutine 
is then listed, which resembles the previous DIV2 program with some 
minor changes. First note that the input floating point value is 
loaded into the BCDE registers so that a temporary copy can be 
manipulated which does not affect the input value. The exponent field 
in register B is decremented by the input count, and returned on the 
stack before the PCHL is executed. 
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PL/I -80 VI. 0, COMPILATION OF: FDTEST 

L: List Source Program 
NO ERROR(S) IN PASS 1 
NO ERROR(S) IN PASS 2 

PL/I-80 VI. 0, COMPILATION OF: FDTEST 



1 


a 0000 


dtest: 






2 


a 0006 


proc options(main) ; 




3 


c 0006 


del 






4 


c 0006 




fdiv2 entry (fixed(7) , float) 




5 


c 0006 




returns (float) , 




6 


c 00 06 




i f ixed(7 ) , 




7 


c 0006 




f float; 




8 


c 0006 








9 


c 0006 




do i =0 by 1; 




10 


c 000A 




put skip list('100 / 2 **',i,'= 




11 


c 0055 




fdiv2(i, 100)) ; 




12 


c 0055 




end; 




13 


a 0055 


end 


dtest; 





CODE SIZE = 0055 
DATA AREA = 0018 
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0000 
0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 



0009 
000A 
000B 
000C 
000D 
0K 
000F 
0010 
0011 
0012 

0015 
0016 
0019 
01A 
001B 



001E 
0021 
0024 
0027 

002A 
002B 
002C 
2D 



0000 
0002 
0004 
006 

0008 
0009 
000A 
000C 
000E 
002A 



fdiv2 



5E 
23 
56 
23 
1A 
5E 
23 
56 
EB 



5E 
23 
56 
23 
4E 
23 
46 
04 
05 
CA2A00 

B7 

CA2A00 

3D 

05 

C21500 



210000 
CD0000 
010000 
110000 

El 
C5 
D5 
E9 



0800 
0900 
0A00 
0C00 

03 

80 

000 

0E00 

20556E64 



public 
extrn 
entry : 

exit: 

stack: 

mov 

inx 

mov 

inx 

ldax 

mov 

inx 

mov 

xchg 



fdiv2 
?signal 

pi -> fixed(7) power of two 
p2 -> floating point number 

pi -> (unchanged) 
p2 -> (unchanged) 
p2 / (2 ** pi) 

;HL = .low(.pl) 
e,m /low(.pl) 
h ;HL = .high(.pl) 
d,m ;DE = .pi 
h ;HL = ,low(p2) 
d ; a = pi (power of two) 
e,m ;low(.p2) 
h ;HL = .high( .p2) 
d ,m ;DE = ,p2 

;HL = .p2 



dby2: 



A = power of 2, 

mo v e , m 

inx h 

mov d r m 

inx h 

mov c,m 

inx h 

mov b,m 

inr b 

dcr b 

jz fdret 
; divide by two 

ora a 

jz fdret 

dcr a 

dcr b 

jnz dby2 



HL = .low byte of fp num 
E = low mantissa 
to middle of mantissa 
D = middle mantissa 
to high byte of mantissa 
C = high mantissa 
to exponent byte 
B = exponent 
B = 00? 

becomes 00 if so 
to return from float div 

; counted power of 2 to zero? 

;return if so 

/count power of two down 

; count exponent down 

;loop again if no underflow 



/underflow occurred, signal underflow condition 



fdret: 



siglst 



sigcod 
sigsub 
sigf il 
sigaux 
65undmsg 



Ixi 
call 
lxi 
lxi 

pop 
push 
push 
pchl 

dseg 

dw 

dw 

dw 

dw 

end of 

db 

db 

dw 

dw 

db 

end 



h, siglst;signal parameter list 
?signal ; signal underflow 
b,0 ;clear to zero 

d,0 ;for default return 



sigcod 
sigsub 
sigf il 
sigaux 
paramete 
3 

128 
0000 
undmsg 
32,'Und 

32 



/recall return address 
;save high order fp num 
;save low order fp num 
/return to calling routine 



/address of signal code 
/address of subcode 
/address of file code 
/address of aux message 
r vector, start of params 
03 = underflow 
arbitrary subcode for id 
no associated file name 
0000 if no aux message 
erflow in Divide by Two',0 



5. PL/I-80 RUNTIME SUBROUTINES. 



The PL/I-80 Runtime Subroutine Library (PLILIB.IRL) is discussed 
in this section, along with the optional subroutines for direct CP/M 
Input Output. The information given here is useful when PL/I-80 is 
used as a "systems language," rather than an application language, 
since direct access to implementation dependent CP/M functions is 
allowed. Note that the use of these features makes your program very 
machine and operating system dependent. 



5*1. Stack and Dynamic Storage Subroutines. 

A number of implementation-dependent functions are included in 
the PL/I-80 Runtime Library which provide access to stack and dynamic 
storage structures. The functions are discussed below, with sample 
programs which illustrate their use. The stack is placed above the 
code and data area, and below the dynamic storage area. The default 
value of the stack size is 512 bytes, but can be changed using the 
STACK (n) option in the OPTIONS portion of the main program procedure 
heading. In general, the PL/I-80 dynamic storage mechanism maintains 
a list of all unallocated storage. Upon each request for storage, a 
search is made to find the first memory segment which satisfies the 
request size. If no storage is found, the ERR0R(7) condition is 
signalled (Free Space Exhausted). Otherwise, the requested segment is 
taken from the free area, and the remaining portion goes back to the 
free space list. In version 1.0 of PL/I-80, storage is dynamically 
allocated only upon entry to RECURSIVE procedures, upon explicit or 
implicit OPENs for files which access the disk, or upon executing an 
ALLOCATE statement. In any case, an even number of bytes, or whole 
words, is always allocated, no matter what the request size. 



5.1.1. The TOTWDS and MAXWDS Functions. It is often useful to 
find the amount of storage available at any given point in the 
execution of a particular program. The TOTWDS (Total Words) and 
MAXWDS (Max Words) functions can be used to obtain this information. 
The functions must be declared in the calling program as 

del totwds returns(f ixed (15) ) ; 
del maxwds returns(f ixed (15) ) ; 

When invoked, the TOTWDS subroutine scans the free storage list and 
returns the total number of words (double bytes) available in the free 
list. The MAXWDS subroutine performs a similar function, but returns 
the size of the largest segment in the free list, again in words. A 
subsequent ALLOCATE statement which specifies a segment size not 
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exceeding MAXWDS will not cause the ERR0R(7) signal to be raised, 
since at least that much storage is available. Note that since both 
TOTWDS and MAXWDS count in word units, the values can be held by FIXED 
BINARY (15) counters. If f during the scan of free memory, invalid link 
words are encountered (usually due to a out-of-bounds subscript or 
pointer store operation), both TOTWDS and MAXWDS return the value -1 . 
Otherwise, the returned value will be a non-negative integer value. 



5.1.2. The ALLWDS Subroutine. The PL/I-80 Runtime Library 

contains a subroutine, called ALLWDS, which is useful in controlling 
the dynamic allocation size. The subroutine must be declared in the 
calling program as 

del allwds entry (fixed (15) ) returns(ptr) ; 

The ALLWDS subroutine allocates a segment of memory of the size given 
by the input parameter, in words (double bytes) . If no segment is 
available, the ERR0R(7) condition is raised. Further, the input value 
must be a non-negative integer value. The ALLWDS function returns a 
pointer to the allocated segment. 

An example of the use of TOTWDS, MAXWDS, and ALLWDS functions is 
given in the ALLTST program on the next page. A sample program 

interaction is given following the program listing. 



5.1.3. The STKSIZ Function. The function STKSIZ (Stack Size) 
returns the current stack size in bytes whenever it is called. This 
function is particularly useful for checking possible stack overflow 
conditions, or in determining the maximum stack depth during program 
testing. The STKSIZ function is declared in the calling program as 

del stksiz returns (fixed (15) ) ; 

A Sample use of the STKSIZ function appears in the listing of 
the recursive Ackermann test. In this case, it is used to check the 
maximum stack depth during the recursive function processing. An 

interaction with this program is given following the program listing. 
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PL/I -80 VI. 0, COMPILATION OF: ALLTST 

L: List Source Program 
NO ERROR(S) IN PASS 1 
NO ERROR(S) IN PASS 2 

PL/I-80 VI. 0, COMPILATION OF: ALLTST 

alltst: 

proc options(main) ; 

/* assembly language interface to 

dynamic storage allocation module */ 

del 

totwds returns(f ixed( 15) ) , 
maxwds returns(f ixed( 15) ) , 
allwds entry ( fixed (15) ) returns (ptr) ; 

del 

allreq fixed(15), 

memptr ptr, 

meminx f ixed(15) , 

memory (0:0) bit(16) based (memptr) ; 

do while('l«b) ; 

put edit ( totwds (),' Total Words Available 

maxwds(),' Maximum Segment Size', 

'Allocation Size? ') 

(2 (skip, f (6) ,a) ,skip,a) ; 
get li st (allreq) ; 
memptr = allwds (allreq) ; 
put edit ( 'Allocated* , allreq, 

• Words at ' ,unspec(memptr) ) 

(skip, a, f (6) ,a,b4) ; 

/* clear memory as example */ 
do meminx = to allreq-1;' 
memory (meminx) = '0000' b4; 
end; 
end; 
end alltst; 

CODE SIZE = 00E7 
DATA AREA = 0078 



1 


a 


0000 


2 


a 


0006 


3 


a 


0006 


4 


a 


0006 


5 


c 


0006 


6 


c 


0006 


7 


c 


0006 


8 


c 


0006 


9 


c 


0006 


10 


c 


0006 


11 


c 


0006 


12 


c 


0006 


13 


c 


0006 


14 


c 


0006 


15 


c 


0006 


16 


c 


0006 


17 


c 


0006 


18 


c 


004F 


19 


c 


004F 


20 


c 


004F 


21 


c 


004F 


22 


c 


0067 


23 


c 


0070 


24 


c 


00B2 


25 


c 


00B2 


26 


c 


00B2 


27 


c 


00B2 


28 


c 


00B2 


29 


c 


0CC 


30 


c 


0E7 


31 


c 


0E7 


32 


a 


0E7 
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A>B:ALLTST 

25596 Total Words Available 
25596 Maximum Segment Size 
Allocation Size? 

Allocated Words at 250A 
25594 Total Words Available 
25594 Maximum Segment Size 

Allocation Size? 100 

Allocated 100 Words at 250E 
25492 Total Words Available 
25492 Maximum Segment Size 

Allocation Size? 25000 

Allocated 25000 Words at 25DA 
490 Total Words Available 
490 Maximum Segment Size 

Allocation Size? 490 

Allocated 490 Words at E92E 
Total Words Available 
Maximum Segment Size 

Allocation Size? 1 

ERROR (7) , Free Space Exhausted 
Traceback: 016D 
End of Execution 
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PL/I-80 VI. r COMPILATION OF: ACKTST 

L: List Source Program 
NO ERROR(S) IN PASS 1 
NO ERROR(S) IN PASS 2 



PL/I-80 VI. f COMPILATION OF: ACKTST 



1 


a 


0000 ack: 


2 


a 


0006 


3 


c 


0006 


4 


c 


0006 


5 


c 


0006 


6 


c 


0006 


7 


c 


0006 


8 


c 


0006 


9 


c 


0006 


10 


c 


0006 


11 


c 


0022 


12 


c 


0046 


13 


c 


005F 


14 


c 


0078 


15 


c 


0088 


16 


c 


008E 


17 


c 


0091 


18 


c 


012F 


19 


c 


012F 


20 


c 


012F 


21 


c 


012F 


22 


c 


012F 


23 


c 


012F 


24 


c 


0132 


25 


c 


0132 


26 


c 


0132 


27 


e 


0132 


28 


e 


015C 


29 


e 


015C 


30 


e 


0177 


31 


e 


017D 


32 


e 


018A 


33 


e 


0190 


34 


e 


0199 


35 


e 


01A1 


36 


e 


01AA 


37 


e 


01BB 


38 


c 


01DC 


39 


a 


01DC 


CODE 


SIZE = 01DC 


DATA 


AREA = 0082 



procedure options (main, stack (2000) ) ; 
del 

( m , n ) f ix ed , 

(maxm,maxn) fixed, 

ncalls decimal(6) , 

(curstack, stacksize) fixed, 

stksiz entry returns( fixed) ; 

put skip list ("Type max m,n: '); 
get 1 ist (maxm f maxn) ; 
do m = to maxm; 

do n = to maxn; 
ncalls = 

curstack = 
stacksize = 
put edit 

('Ack(' ,m, 
nc alls ' 
( skip, a ',2 (f (2) ,a) ,f (6) ,f (7) ,a,f (4) ,a) 



1 r' »n,')=' ,ackermann(m,n) , 
Calls,' , stacksize , * Stack Bytes') 



e 
stop; 



nd; 



end; 



returns(f ixed) recursive; 



ackermann : 

procedure (m,n) 
del 

(m,n) fixed; 
ncalls = ncalls + 1; 
curstack = stksizO; 
if curstack > stacksize then 

stacksize = curstack; 
if m = then 

return (n+1 ) ; 
if n = then 

return (ackermann (m-1 ,1) ) ; 
return (ackermann (m-1 , ackermann (m,n-l) ) ) 
end ackermann; 
end ack; 
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A>B:ACKTST 



Type max m,n: 6,6 



Ack( 


0. 


0) = 


1 


1 


Calls, 


4 


Stack 


Bytes 


Ackl 


0, 


r D = 


2 


1 


Calls, 


4 


Stack 


Bytes 


Ackl 


0i 


f 2) = 


3 


1 


Calls, 


4 


Stack 


Bytes 


Ack 


( 


r 3) = 


4 


1 


Calls, 


4 


Stack 


Bytes 


Ackl 


' 


r 4) = 


5 


1 


Calls , 


4 


Stack 


Bytes 


Ack 


[ 0- 


r 5) = 


6 


1 


Calls, 


4 


Stack 


Bytes 


Ack( 


0i 


6) = 


7 


1 


Calls, 


4 


Stack 


Bytes 


Ack( 


1 


r 0) = 


2 


2 


Calls, 


6 


Stack 


Bytes 


Ack< 


1, 


D = 


3 


4 


Calls , 


8 


Stack 


Bytes 


Ackl 


' 1, 


r 2) = 


4 


6 


Calls, 


10 


Stack 


Bytes 


Ack I 


' 1, 


3) = 


5 


8 


Calls, 


12 


Stack 


Bytes 


Ack I 


' 1, 


r 4) = 


6 


10 


Calls, 


14 


Stack 


Bytes 


Ack I 


' 1, 


r 5) = 


7 


12 


Calls, 


16 


Stack 


Bytes 


Ack( 


1, 


6) = 


8 


14 


Calls, 


18 


Stack 


Bytes 


Ack< 


2 


r 0) = 


3 


5 


Calls, 


10 


Stack 


Bytes 


Ackl 


2, 


D = 


5 


14 


Calls, 


14 


Stack 


Bytes 


Ackl 


2, 


2) = 


7 


27 


Calls, 


18 


Stack 


Bytes 


Ack| 


2 


r 3) = 


9 


44 


Calls, 


22 


Stack 


Bytes 


Ack | 


2 


r 4) = 


11 


65 


Calls, 


26 


Stack 


Bytes 


Ackl 


2 


r 5) = 


13 


90 


Calls, 


30 


Stack 


Bytes 


Ackl 


2, 


6) = 


15 


119 


Calls, 


34 


Stack 


Bytes 


Ackl 


3, 


0) = 


5 


15 


Calls, 


16 


Stack 


Bytes 


Ackl 


3, 


D = 


13 


106 


Calls, 


32 


Stack 


Bytes 


Ack 


' 3 


r 2) = 


29 


541 


Calls, 


64 


Stack 


Bytes 


Ack 


[ 3, 


, 3) = 


61 


2432 


Calls, 


128 


Stack 


Bytes 


Ack 


[ 3 


r 4) = 


125 


10307 


Calls , 


256 


Stack 


Bytes 


Ack 


( 3 


r 5) = 















38 



5.2. PL/I-80 Runtime Subroutine Entry Points. 

The standard PL/I-80 Runtime Library entry points are listed 
below. The entry point name is shown to the left, followed by the 
input value registers and the result registers. A short explanation 
is given on the right. Note that this list does not include the 
environmental or I/O operators since these entry points may vary from 
version to version. Further, the definitions shown below are for 
general information purposes only, and are subject to change without 
notice. The register names are given in capital letters, M(r) denotes 
memory addressed by the register pair r, and ST represents a stacked 
value. 



name parameters result comment or definition 



im22n DE HL HL word*word integer multiply 
id22n DE HL HL word/word integer divide 
is22n DE HL HL word-word integer subtract 
in20n HL HL -word 

fl40m HL ST fp load from M(HL) to stack 

fx44s ST HL M(HL) fp xfer from stack to M(HL) 
fx44m DE HL M(HL) fp xfer from M(HL) to M(DE) 
fa44s ST ST ST fp add stack+stack to stack 
fa44m DE HL ST fp add M(DE)+M(HL) to stack 
fa441 ST HL ST fp add stack+M(HL) to stack 
fa44r HL ST ST fp add M(HL)+stack to stack 
fs44s ST ST ST fp sub stack-stack to stack 
fs44m DE HL ST fp sub M(DE)-M(HL) to stack 
fs441 ST HL ST fp sub stack-M(HL) to stack 
fs44r HL ST ST fp sub M(HL)-stack to stack 
fm44s ST ST ST fp mul stack*stack to stack 
fm44m DE HL ST fp mul M(DE)*M(HL) to stack 
fm441 ST HL ST fp mul stack*M(HL) to stack 
fm44r HL ST ST fp mul M(HL)*stack to stack 
fd44s ST ST ST fp div stack/STack to stack 
fd44m DE HL ST fp div M(DE)/M(HL) to stack 
fd441 ST HL ST fp div stack/M(HL) to stack 
fd44r HL ST ST fp div M(HL)/STack to stack 
fc44s ST ST ST fp comp stack:stack to stack 
fc44m DE HL ST fp comp M(DE):M(HL) to stack 
fc441 ST HL ST fp comp stack:M(HL) to stack 
fc44r HL ST ST fp comp M(HL):stack to stack 
fn40s ST ST fp negate stack 

fn40m HL ST fp load from M(HL) and negate 

fe40s ST A float p extract sign from stack 

fe40m HL A float p extract sign from memory 

1 => positive sign (non zero set) 
=> zero result (zero flag set) 
-1 => negative sign (minus set) 
floating point mod(x,y) 
floating point abs(x) 
floating point max(x,y) 
floating point min(x,y) 



fmodf 


ST 


ST 


ST 


fabsf 


ST 




ST 


fmaxf 


ST 


ST 


ST 


fminf 


ST 


ST 


ST 
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f roun 


ST 




A 


ST 


f trnc 


ST 






ST 


fflor 


ST 






ST 


fceil 


ST 






ST 


f exop 


ST 




A 


ST 


f fxop 


ST 




ST 


ST 


bcl2n 


D 




HL 


HL 


bc22n 


DE 




HL 


HL 


bsll6 


B 




HL 


HL 


bsl08 


A 




B 


A 


bst08 


A B 


C 


HL 


M(HL) 


bstl6 


B C 


DE HL 


M(HL) 


bix08 


A B 


D 


H 


A/HL 


bixl6 


B C 


DE HL 


A/HL 



boolf 



slcts 



ssvf s 



B 



DE HL 



HL 



HL 



iel2n 


A 




HL 


iel0n 


A 




A 


ie20n 


HL 




A 


imdop 


DE 


HL 


HL 


iab07 


A 




A 


iabl5 


HL 




HL 


imaxf 


DE 


HL 


HL 


iminf 


DE 


HL 


HL 


iroun 


HL 


A 


HL 


iexop 


HL 


A 


HL 


slvts 


HL 




A 



HL 



sscf s 


A 




B 


HL 


smvvra 


A 




DE 


HL 


smvcm 


A 




DE 


HL 


smcvm 


A 


B 


DE 


HL 


smccm 


A 


B 


DE 


HL 


sjsts 


A 




ST 


ST' 



sjscm 



HL 



floating point round(x,k) 
floating point trunc(x) 
floating point floor(x) 
floating point ceil(x) 
fp ** k (k pos constant) 



** 



y (exp(y*log(x) ) 



8/16 bit concatenate, where 

B=length of d, C=mask 

16/16 bit concatenate, where 

B=length of d, C=mask 

bit shift left 16, size in b 

bit shift left 8, size in b 

bit substring store bit(8) in 

A to bit(8) in memory at HL, 

B = index, C = length 

bit substring store bit(16) in 

DE to bit(16) in memory at HL 

bit index, A=source, B=search 

D=len(source) , E=len(search) 

bit index, B=len(source) , 

C=len(search) , DE=source, 

HL=search 

bool(x,y,b), B = 4-bit mask 

x,y operands in DE and HL 

sign extend A to HL 

integer extract sign (8-bit) 

integer extract sign (16-bit) 

integer mod(x,y) 

integer 7 abs(i) 

integer 15 abs(i) 

integer max(x,y) 

integer min(x,y) 

integer round(i,k) 

integer ** k (k pos constant) 

string load varying to stack 

A=length of string on return 

string load char to stack 

A=length of char string 

string store varying from stack 

A=current len, B=max length 

string store char from stack 

string move vary to vary in memory 

A=max target len, DE=source, HL=target 

string move vary to char in memory 

A=target length 

string move char to vary in memory 

A=max target len, B=source len 

A=target len, B=source len 

string juxtapose (catenate) stack 

A=length of left, ST=chars of left 

ST* = pushed psw with length of right 

followed by chars of right 

string juxtapose stack with char memory 

A^stacked len, B=char len, HL=.char 
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sjsvm 


A 






HL 


savvm 


A 




B 


HL 


sasvm 


A 




B 


HL 


sacvm 


A 




B 


HL 


scccm 


A 


B 


DE 


HL 


sccvm 




B 


DE 


HL 


scvcm 


A 




DE 


HL 


scvvm 






DE 


HL 


scscm 


A 


B 




HL 


scsvm 


A 






HL 


sc cms 


A 


B 




HL 


scvms 


A 






HL 


scsts 


A 









cs2ad 



cs3ad ACE 



vs2ad 



vs3ad 



C E 



cxccm A B DE 



HL 



HL 



HL 



HL 



A/HL 



cxcvm 




B 


DE 


A/HL 


cxvcm 


A 




DE 


A/HL 


cxvvm 






DE 


A/HL 


cxscm 


A 


B 




A/HL 



string juxtapose stack with vary memory 

string append vary to vary in memory 

A=char len, B=max target length 

string append stack to vary in memory 

A=stacked length, B=max target length 

string append char to vary in memory 

A=char len, B=max target length 

string compare char to char in memory 

A=len right, B=len left, 

DE = .char left, HL = .char right 

string compare char to vary in memory 

B=len left, DE=.char, HL=.vary 

string compare vary to char in memory 

A=len right char, DE=.vary, HL=.char 

string compare vary to vary in memory 

DE=.vary left, HL=.vary right 

string compare stack to char in memory 

A=len stk, B=len char, HL=.char 

string compare stack to vary in memory 

A=len stk, HL=.vary 

string compare char in mem to stack 

A=len stk, B=len char, HL=.char 

string compare vary in mem to stack 

A=len stk, HL=.vary 

string compare stack to stack 

A=len right element on stack, 

ST is stack right string, next is 

pushed psw with len left string, 

followed by left string, result: 

sign value & cond if 1 < r, 

zero value & cond if 1 = r, 

pos value & cond if 1 >= r, 

nzer value & cond if 1 > r. 

char substr (ex,ei) address 

A=length, E=ei, HL=ex 

A=result length on return 

char substr (ex, ei, el) address 

C=el 

A=result length on return 

vary substr (ex, ei) address 

E=ei, HL=ex 

A=result length on return 

vary substr (ex, ei , el) address 

C=el 

A=result length on return 

str index char to char in memory 

A=len right, B=len left, 

DE = .char left, HL = .char right 

str index char to vary in memory 

B=len left, DE=.char, HL=.vary 

str index vary to char in memory 

A=len right char, DE=.vary, HL=.char 

str index vary to vary in memory 

DE=.vary left, HL=.vary right 

str index stack to char in memory 
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cxsvm 


A 




A/HL 


ex cms 


A 


B 


A/HL 


cxvms 


A 




A/HL 


exsts 


A 







verop 

co lop 
xl2op 

xl3op 



dldop 
dasop 
dadop 
dsuop 
dngop 
demop 
dexop 
dmuop 
ddvop 
dsiop 
dmodf 
dabsf 
dmaxf 
dminf 
droun 
dtrnc 
dflor 
dceil 
dexop 
qcdop 



ST ST 



A 

A 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

A 



qddsl 


A 


qddsr 


A 


qicop 


A 


qvcop 
qi07d 
qil5d 
q!07f 


A/ST 
A 

HL 
A 



HL 
ST 
ST 
ST 



ST 
ST 
ST 

ST 

ST 
ST 
A 



A 
ST 



A/ A/HL 

A/ST 
A/ST 



A ST ST 

A ST ST ST A/ST 



ST 

HL 

ST 

ST 

ST 

A 

ST 

ST 

ST 

A 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 

ST 



ST 


ST 


ST 


ST 




HL 




A/ST 




ST 




ST 




ST 



A=len stk, B=len char, HL=.char 

str index stack to vary in memory 

A=len stk, HL=. vary 

str index char in mem to stack 

A=len stk, B=len char, HL=.char 

str index vary in mem to stack 

A=len stk, HL=.vary 

str index stack to stack 

A=len right element on stack, 

ST is stack right string, next is 

pushed psw with len left string, 

followed by JLeft string, result: 

A/HL = if right not found in 

left, otherwise index returned 

verify(s,c) , A=len(c) , st 

has chars(c) ,len(s) ,chars(s) 

collate() , A=128, stack has 

translate(s,t) , A=len(t) , 

stack has chars(t) , s 

translate(s,t ,x) A=len(x) , 

stack has chars(x) , t, s 

0,1, ..., 127 (ascii chars) 

decimal load to stack, A = prec 

decimal assign, stack to memory 

decimal add to stack 

decimal subtract to stack 

decimal negate to stack 

decimal compare operator 

decimal exponentiate to stack 

decimal multiply to stack 

decimal divide to stack 

decimal sign extract 

decimal mod(x,y) 

decimal abs(x) 

decimal max (x ,y) 

decimal min(x,y) 

decimal round(x,k) 

decimal trunc(x) 

decimal floor (x) 

decimal ceil(x) 

decimal ** k (k pos constant) 

convert character to decimal 

A = string length, B = scale 

ST = character string, returns 

ST = decimal number 

decimal/decimal left shift 

A = shift count 

decimal/decimal right shift 

A = shift count 

convert integer to char in stack 

A=string size, HL=integer value 

convert varying to char 

convert fix(7) to decimal 

convert fix(15) to decimal 

convert fix (7) to float 



42 



qil5f 
qfi07 
qfil5 
qfcss 

qfcms 
qb08c 

qbl6c 
qb0 8i 

qbl6i 
qi07b 

qil5b 
qdi07 
qdil5 
qciop 
qcfop 
qccop 



nstop 
nc22n 

ncomp 



M(HL) A/ST 
B ST 



ST convert fix(15) to float 
A convert float to fix(7) 
HL convert float to fix(15) 
ST A/ST convert float-char stack to stack 
A=target length, ST=fp number 
convert float-char memory to stack 
convert bit(8) in a r to string 
in stack, with precision b 
ST convert bit(16) in HL to string 
HL convert bit(8) in A to fixed 

with precision B in HL 
HL convert bit(16) to fixed 
A convert fix(<8) to bit(8) 
fixed precision in b 
B HL convert fix(<16) to bit(16) 

A convert dec in stack to fix(7) 
HL convert dec in stack to fix (15) 
HL convert char in stack to integer 
ST convert char in stack to float 
ST A/ST convert char to char on stack 
A=len(s) , B=converted length 
return A=b, ST trunc or extend 
non-computational store, move 
M(DE) to M(HL) for BC bytes 
double byte non-computational 
compare: zero flag set if 
DE = HL, non-zero otherwise 
BC DE HL M(HL) non-computational compare, 

M(DE) - M(HL), set flags. 



HL 
ST 
ST 
A 

A 
A 

HL 
A 

HL 
A 

HL 

ST 

ST 

A/ST 

A/ST 

A B 



BC DE HL M(HL) 
DE HL A 



5.3. Direct CP/M Function Calls. 

Access to all CP/M version 1 and 2 functions, and equivalent 
MP/M calls, is accomplished through the optional subroutines included 
in PLIDIO.ASM, given in the listing of Appendix A, and included in 
source form on the PL/I-80 diskette. 

The PLIDIO.ASM subroutines are not included as a part of the 
standard PLILIB.IRL file because specific applications may require 
various changes to the direct CP/M functions which either remove 
operations to decrease space, or alter the manner in which the 
interface to a specific function takes place. Note that if the 
interface to a function is changed, it is imperitive that the name of 
the entry point is also changed to avoid confusion when the program is 
read by another programmer. 



The relocatable file, PLIDIO.REL, is created by 
source program using RMAC: 



assembling the 



rmac plidio $pz+s 
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(the $pz+s option avoids production of the listing and symbol files). 
Given that a PL/I-80 program, such as DIOCOPY.PLI, is present on the 
disk, the DIOCOPY.REL file is produced by typing: 

pli diocopy 

(a listing of the DIOCOPY program is given in Appendix C) . These two 
programs are then linked with the PLILIB.IRL file by typing: 

link diocopy , pi id io 

resulting in the file DIOCOPY.COM which is a program that directly 

executes under CP/M. 

The file DIOMOD.DCL is a source file containing the standard 
PLIDIO entry point declarations so that they can be conveniently 
copied into the source program during compilation using the "include" 
statement 

%include 'x:diomod.dcl* ; 

where the optional "x:" drive prefix indicates the drive name (A: 

through P:) containing the DIOMOD.DCL file. The drive prefix need not 

be present if the DIOMOD.DCL file is on the same drive as the PLI 

source file. The contents of the DIOMOD.DCL file is shown below, and 
in the listing of Appendix C. 



del 



memptr 


entry 


memsiz 


entry 


memwds 


entry 


dfcb0 


entry 


dfcbl 


entry 


dbuff 


entry 


reboot 


entry, 


rdcon 


entry 


wrcon 


entry 


rdrdr 


entry 


wrpun 


entry 


wrist 


entry 


coninp 


entry 


conout 


entry 


rdstat 


entry 


getio 


en t ry 


setio 


entry 


wrstr 


entry 


rdbuf 


entry 


break 


entry 


vers 


entry 


reset 


entry, 


select 


entry 


open 


entry 


close 


entry 


sear 


entry 



returns 
returns 
returns 
returns 
returns 
returns 



ptr) , 

fixed(15) ) 
fixed(15) ) 
ptr) , 
ptr) , 
Ptr) , 



returns (char (1) ) , 

(char(l) 

returns (char (1) ) , 

(char(l) 

(char(l) 

returns (char (1) ) , 

(char(l) 

returns (bit(l) ) , 

returns (bit (8) ) , 

(bit(8)) , 

(ptr) , 

(ptr) , 

returns (bit (1) ) , 

returns (bit (16) ) , 

(fixed(7)) , 
(ptr) returns (fixed(7) ) , 
(ptr) returns (fixed(7)), 
(ptr) returns (fixed(7) ) , 
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searn 


entry 




returns 


(fixed(7)) , 


delete 


entry 


(ptr) 


r 




rdseq 


entry 


(ptr) 


returns 


(fixed(7) ) , 


wrseq 


entry 


(ptr) 


returns 


(fixed(7)) , 


make 


entry 


(ptr) 


returns 


(fixed(7)) , 


rename 


entry 


(ptr) 


r 




logvec 


entry 




returns 


(bit(16)) , 


curdsk 


entry 




returns 


(fixed(7) ) , 


setdma 


entry 




(ptr) , 




allvec 


entry 




returns 


(Ptr) , 


wpdisk 


e n t ry , 








rovec 


entry 




returns 


(bit(16)) , 


f ilatt 


entry 




(ptr) , 




getdpb 


entry 




returns 


(ptr) , 


getusr 


entry 




returns 


(fixed(7)) , 


setusr 


entry 


(fixed(7)) , 




rdran 


entry 


(ptr) 


returns 


(fixed(7) ) , 


wrran 


entry 


(Ptr) 


returns 


(fixed(7) ) , 


f ilsiz 


entry 


(ptr) 


r 




setrec 


entry 


(ptr) 


f 




resd rv 


entry 




(bit(16)) 


•r 


wrranz 


entry 


(Ptr) 


r e t ur n s 


(fixed(7) ) ; 



Three programs are included which illustrate the use of the 
PLIDIO calls. Appendix B lists the DIOCALLS program that gives 

examples of all the basic functions, while Appendix C shows how the 
fundamental disk I/O operations take place, in a program called 
DIOCOPY which performs a fast file-to-file copy function. The last 

program, given in Appendix D, illustrates the operation of the random 
access primitives. These programs are designed to demonstrate all of 
the PLIDIO entry points, and show various additional PL/I-80 

programming facilities in the process. 

The file FCB.DCL is used throughout DIOCOPY and DIORAND to 
define the body of each File Control Block declaration. This file is 
copied into the source program during compilation using the statement: 



%include 'xrfcb.dcl'; 

where, again, "x:" denotes the optional drive 
containing the FCB.DCL file. 



prefix for the drive 



Note that the use of these entry points generally precludes the 
use of some PL/I-80 facilities. In particular, the dynamic storage 
area is used by the PL/I-80 system for recursive procedures and file 
I/O buffering. (Be aware that there are no guarantees that the 

dynamic storage area will not be used for other purposes as additional 
facilities are added to PL/I-80.) Thus, the use of the MEMPTR function 
as shown in Appendix B disallows the use of dynamic storage allocation 
functions. Further, you must ensure that the various file maintenance 
functions, such as delete and rename do not access a file which is 
currently open in the PL/I-80 file system. Simple peripheral access, 
as shown in these examples, is generally safe since no buffering takes 
place in this case. 
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APPENDIX A: 

LISTING OF "PLIDIO" 
DIRECT CP/M CALL ENTRY POINTS 
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:p/m rmac assem 0.4 



#001 



DIRECT CP/M CALLS FROM PL/I-80 



name 'DIOMOD' 

title 'Direct CP/M Calls From PL/I-80' 



********************** 

* 

* cp/m calls from 

* 

************** 



publi 

publi 

publi 

publi 

publi 

publi 

publi 

publi 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

publ 

public 



c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 

ic 



******** 

memptr 

memsiz 

memwds 

dfcb0 

dfcbl 

dbuff 

reboot 

rdcon 

wrcon 

rdrdr 

wrpun 

wrist 

coninp 

conout 

rdstat 

ge tio 

setio 

wrstr 

rdbuf 

break 

vers 

reset 

select 

open 

close 

sear 

searn 

delete 

rdseq 

wrseq 

make 

rename 

logvec 

curdsk 

setdma 

allvec 

wpdisk 

rovec 

filatt 

getdpb 

getusr 

setusr 

rdran 

wrran 

f ilsiz 

setrec 

resdrv 

wrranz 



************************************* 

* 

pl/i for direct i/o * 

* 

************************************* 

return pointer to base of free mem 

return size of memory in bytes 

return size of memory in words 

return address of default fcb 

return address of default fcb 1 

return address of default buffer 

system reboot (#0) 

read console character (#1) 

write console character (#2) 

read reader character (#3) 

write punch character (#4) 

write list character (#5) 

direct console input (#6a) 

direct console output (#6b) 

read console status (#6c) 

get io byte (#8) 

set i/o byte (#9) 

write string (#10) 

read console buffer (#10) 

get console status (#11) 

get version number (#12) 

reset disk system (#13) 

select disk (#14) 

open file (#15) 

close file (#16) 

search for file (#17) 

search for next (#18) 

delete file (#19) 

read file sequential mode (#20) 

write file sequential mode (#21) 

create file (#22) 

rename file (#23) 

return login vector (#24) 

return current disk number (#25) 

set DMA address (#26) 

return address of alloc vector (#27) 

write protect disk (#28) 

return read/only vector (#29) 

set file attributes (#30) 

get base of disk parm block (#31) 

get user code (#32a) 

set user code (#32b) 

read random (#33) 

write random (#34) 

random file size (#35) 

set random record pos (#36) 

reset drive (#37) 

write random, zero fill (#40) 
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CP/M RMAC ASSEM 0.4 



#0 02 



DIRECT CP/M CALLS FROM PL/I-80 



00D 
000A 
001A 

0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
000A 
0B 
00C 
000D 
000E 
00 0F 
0010 
0011 
0012 
0013 
0014 
0015 
0016 
0017 
0018 
0019 
001A 
001B 
001C 
001D 
001E 
001F 
020 
0021 
0022 
0023 
0024 
0025 
0028 



extrn 
extrn 
extrn 
extrn 
extrn 
extrn 



?begin 

?boot 

?bdos 

?dfcb0 

?dfcbl 

?dbuff 



beginning of free list 
system reboot entry point 
bdos entry point 
default fcb 
default fcb 1 
default buffer 



********************************************************** 

* 

* 

* 

****** 



equates for interface to cp/m bdos 



**************************************************** 

cr equ 0dh ;carriage return 

If jequ 0ah ;line feed 

eof equ lah ;end of file 

readc equ 1 ;read character from console 

write equ 2 ;write console character 

rdrf equ 3 ; reader input 

punf equ 4 ; punch output 

listf equ 5 ;list output function 

diof equ 6 ;direct i/o, version 2.0 

getiof equ 7 ;get i/o byte 

setiof equ 8 ;set i/o byte 

printf equ 9 ;print string function 

rdconf equ 10 ;read console buffer 

statf equ 11 ; return console status 

versf equ 12 ;get version number 

resetf equ 13 ; system reset 

seldf equ 14 ;select disk function 

openf equ 15 ;open file function 

closef equ 16 ;close file 

serchf equ 17 ; search for file 

serchn equ 18 ;search next 

deletf equ 19 ;delete file 

readf equ 20 ;read next record 

writf equ 21 ;write next record 

makef equ 22 ;make file 

renamf equ 23 /rename file 

loginf equ 24 ;get login vector 

cdiskf equ 25 ;get current disk number 

setdmf equ 26 ;set dma function 

getalf equ 27 ;get allocation base 

wrprof equ 28 ;write protect disk 

getrof equ 29 ;get r/o vector 

setatf equ 30 ;set file attributes 

getdpf equ 31 ;get disk parameter block 

userf equ 32 ; set/get user code 

rdranf equ 33 ;read random 

wrranf equ 34 ;write random 

filszf equ 35 ;compute file size 

setrcf equ 36 ;set random record position 

rsdrvf equ 37 ; reset drive function 

wrrnzf equ 40 ;write random zero fill 
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P/M RMAC ASSEM 0.4 



#003 



DIRECT CP/M CALLS FROM PL/I-80 



0000 


5E 


0001 


23 


0002 


56 


0003 


EB 


0004 


5E 


0005 


C9 



utility functions 
**************************************************** 



general purpose routines used upon entry 



*********************************************************** 

getpl: ;get single byte parameter to register e 

mov e,m ;low (addr) 
inx h 

mov d,m ;high(addr) 

xchg ;hl = .char 

mov e,m ;to register e 
ret 



0006 


CD0000 


0009 


23 


000A 


56 


000B 


C9 


000C 


E5 


00D 


0E0C 


000F 


CD0000 


0012 


El 


0013 


C9 


0014 


CD0C00 


0017 


FE14 


0019 


D0 


001A 


C32300 


001D 


CD0C00 


0020 


FE22 


0022 


D0 


0023 


112E00 


0026 


0E09 


0028 


CD0000 


002B 


C30000 


002E 


0D0A4C 



getp2: ;get single word value to DE 
getp2i: ; (equivalent to getp2) 

call getpl 

inx h 

mov d,m ;get high byte as well 

ret 

getver: ;get cp/m or mp/m version number 

push h ;save possible data adr 

mvi c f versf 

call ?bdos 

pop h ;recall data addr 

ret 

> 

chkv20: ; check for version 2.0 or greater 

call getver 

cpi 20 

rnc ;return if > 2.0 

; error message and stop 

jmp vererr ;version error 

chkv22: ; check for version 2.2 or greater 

call getver 

cpi 22h 

rnc ;return if >= 2.2 

vererr: 

/version error, report and terminate 

lxi d,vermsg 

mvi c,printf 

call ?bdos ; write message 

jmp ?boot ;and reboot 



0D0A4C6174vermsg: db 



cr r l£ r 'Later CP/M or MP/M Version Required$' 



0054 
0057 



2A0000 
C9 



*********************************************************** 
* * 

*********************************************************** 

memptr: /return pointer to base of free storage 
lhld ?begin 
ret 
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CP/M RMAC ASSEM 0.4 



#004 DIRECT CP/M CALLS FROM PL/I-80 



0058 2A0100 

005B EB 

005C 2A0000 

005F 7B 

0060 95 

061 6F 

0062 7A 

0063 9C 

0064 67 

0065 C9 



0066 CD5800 

0069 7C 
006A B7 
006B IF 
006C 67 
06D 7D 
006E IF 
006F 6F 

0070 C9 



0071 210000 
0074 C9 



0075 210000 
0078 C9 



0079 210000 
007C C9 



*********************************************************** 
* * 

*********************************************************** 



memsiz: ;return size of free memory in bytes 



lhld 


?bdos+l 


xchg 




lhld 


?begin 


mov 


a,e 


sub 


1 


mov 


Ira 


mov 


a r d 


sbb 


h 


mov 


h,a 


ret 





call 


memsiz 


mov 


a,h 


ora 


a 


rar 




mov 


h,a 


mov 


a,l 


rar 




mov 


l,a 


ret 





007D C30000 



base of bdos 

de = .bdos 

beginning of free storage 

low( .bdos) 

-low(begin) 

back to 1 

high( .bdos) 

;hl = mem size remaining 



*********************************************************** 

* * 
*********************************************************** 

memwds: ; return size of free memory in words 

hi = size in bytes 

high (size) 

cy = 

cy = Is bit 

back to h 

low (size) 

include Is bit 

back to 1 

with wds in hi 

************************************************** 

* * 
*********************************************************** 

dfcb0: ; return address of default fcb 
lxi h,?dfcb0 
ret 

*********************************************************** 

* * 
*********************************************************** 

dfcbl: ; return address of default fcb 1 
lxi h,?dfcbl 

ret 

*********************************************************** 

* * 
*********************************************************** 

dbuff: ; return address of default buffer 
lxi h,?dbuff 

ret 

*********************************************************** 

* * 
*********************************************************** 

reboot: ; system reboot (#0) 
jmp ?boot 
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IP/M RMAC ASSEM 0.4 



#005 DIRECT CP/M CALLS FROM PL/I-80 



0080 0E01 
0082 C38C00 



0085 0E02 
0087 C39C00 



008A 0E03 



008C CD0000 
008F El 

0090 F5 

0091 33 

0092 3E01 
0094 E9 



0095 0E04 
0097 C39C00 



009A 0E05 



009C CD0000 
009F C30000 



*************************************************** 

* * 
*********************************************************** 

rdcon: ; read console character (#1) 

; return character value to stack 

mvi c,readc 

jmp chrin ; common code to read char 

*********************************************************** 

* * 
*********************************************************** 

wrcon: ;write console character (#2) 
;l->char(l) 

mvi c, write ;console write function 
jmp chrout ;to write the character 

*********************************************************** 

* * 
*********************************************************** 

rdrdr: ;read reader character (#3) 

mvi c,rdrf ;reader function 

chrin: 

;common code for character input 



call ?bdos 

pop h 

push psw 

inx sp 

mvi a,l 
pchl 



value returned to A 
return address 
character to stack 
delete flags 
character length is 1 
back to calling routine 



00A2 21AE00 
00A5 E5 



*********************************************************** 

* * 
*********************************************************** 

wrpun: ;write punch character (#4) 
;l->char(l) 

mvi c r punf ;punch output function 

jmp chrout ;common code to write chr 

*********************************************************** 

* * 
*********************************************************** 

wrist: ;write list character (#5) 

;l->char(l) 

mvi c,listf ;list output function 
chrout: 

;common code to write character 

; l-> character to write 

call getpl ;output char to register e 

jmp ?bdos ;to write and return 

*********************************************************** 

* * 
*********************************************************** 

coninp: ;perform console input, char returned in stack 
lxi h,chrstr ; return address 
push h ?to stack for return 
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CP/M RMAC ASSEM 0.4 



#006 



DIRECT CP/M CALLS FROM PL/I-80 



00A6 2A0100 
00A9 110600 
00AC 19 
0AD E9 



0AE El 
0AF F5 
00B0 33 
00B1 E9 



00B2 CD0000 
00B5 4B 
00B6 2A0100 
00B9 110900 
00BC 19 
00BD E9 



00BE 21EC00 
00C1 E5 
00C2 2A0100 
00C5 110300 
00C8 19 
00C9 E9 



00CA 0E07 
00CC C30000 



00CF CD0000 
00D2 0E08 
00D4 C30000 



lhld 


?boot+l 


lxi 


d,2*3 


dad 


d 


pchl 





00D7 CD0600 



;base of bios jmp vector 
;offset to jmp conin 

;return to chrstr 

chrstr: ;create character string, length 1 

pop h ;recall return address 

push psw ;save character 

inx sp ; delete psw 

pchl ;return to caller 

********************************* ************************** 

* * 
*********************************************************** 

conout: ;direct console output 
;l->char(l) 

call get pi ;get parameter 

mov c,e ;character to c 

lhld ?boot+l ;base of bios jmp 

lxi d,3*3 ;console output offset 

dad d ;hl = .jmp conout 

pchl ; return through handler 

*********************************************************** 

* * 
*********************************************************** 

rdstat: /direct console status read 

lxi h,rdsret ;read status return 

push h ; return to rdsret 

lhld ?boot+l ;base of jmp vector 

lxi d f l*3 ;offset to .jmp const 

dad d ;hl = .jmp const 
pchl 

*********************************************************** 

* * 
*********************************************************** 

getio: ;get io byte (#8) 
mvi c,getiof 

jmp ?bdos ;value returned to A 

*********************************************************** 

* * 
*********************************************************** 

setio: ;set i/o byte (#9) 
;l->i/o byte 

call getpl ;rtew i/o byte to E 

mvi c,setiof 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

wrstr: ;write string (#10) 
; l-> add r( string) 
call getp2 ;get parameter value to DE 
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/M RMAC ASSEM 0.4 



#007 DIRECT CP/M CALLS FROM PL/I-80 



0DA 0E09 
0DC C30000 



mvi 
jmp 



c r pr intf 
?bdos 



;print string function 
; return through bdos 



0DF CD0600 
0E2 0E0A 
0E4 C30000 



J0E7 0E0B 
J0E9 CD0000 



J0EC B7 
30ED C8 
30EE 3EFF 
30F0 C9 



30F1 0E0C 
00F3 C30000 



00F6 0E0D 
00F8 C30000 



00FB CD0000 
00FE 0E0E 
0100 C30000 



0103 CD0600 
0106 0E0F 
0108 C30000 



****************************************************** 

* * 
*********************************************************** 

rdbuf: ;read console buffer (#10) 
;l->addr(buff) 

call getp2i ;DE = .buff 

mvi c,rdconf ;read console function 

jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

break: ;get console status (#11) 
mvi c,statf 

call ?bdos ; return through bdos 

7 

rdsret: ; return clean true value 

ora a ;zero? 

rz ;return if so 

mvi a,0ffh ;clean true value 

ret 

*********************************************************** 

* * 
*********************************************************** 

vers: ;get version number (#12) 
mvi c,versf 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

reset: ;reset disk system (#13) 
mvi c,resetf 

jmp ?bdos 

*********************************************************** 

* * 
*********************************************************** 

select: ;selectdisk (#14) 

;l->fixed(7) drive number 

call getpl ;disk number to E 

mvi c f seldf 

jmp ?bdos ;return through bdos 

*********************************************************** 

* * 
*********************************************************** 

open: ;open file (#15) 
;l-> addr(fcb) 

call getp2i ;fcb address to de 

mvi c r openf 
jmp ?bdos ; return through bdos 
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CP/M RMAC ASSEM 0.4 



#008 DIRECT CP/M CALLS PROM PL/I-80 



010B CD0600 
010E 0E10 
0110 C30000 



0113 CD0600 
0116 0E11 
0118 C30000 



011B 0E12 
011D C30000 



0120 CD0600 
0123 0E13 
0125 C30000 



0128 CD0600 
012B 0E14 
012D C30000 



0130 CD0600 
0133 0E15 
0135 C30000 



************************************************* 

* * 
*********************************************************** 

close: ;close file (#16) 
;l-> addr(fcb) 

call getp2i ;.fcb to DE 

mvi c, close f 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

sear: ;search for file (#17) 
;l-> addr(fcb) 

call getp2i ;.fcb to DE 

mvi c,serchf 
jmp ?bdos 

*********************************************************** 

* * 
*********************************************************** 

searn: ;search for next (#18) 

mvi c,serchn ;search next function 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

delete: ;delete file (#19) 
;l-> addr(fcb) 

call getp2i ;.fcb to DE 

mvi c,deletf 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

rdseq: ;read file sequential mode (#20) 
?l-> addr(fcb) 

call getp2i ;.fcb to DE 

mvi c,readf 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

wrseq: ;write file sequential mode (#21) 
;l-> addr(fcb) 

call getp2i ; .fcb to DE 

mvi c,writf 

jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

make: ;create file (#22) 
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P/M RMAC ASSEM 0.4 



#009 DIRECT CP/M CALLS FROM PL/I-80 



0138 CD0600 
013B 0E16 
013D C30000 



0140 CD0600 
0143 0E17 
0145 C30000 



0148 0E18 
014A C30000 



014D 0E19 
014F C30000 



0152 CD0600 
0155 0E1A 
0157 C30000 



015A 0E1B 
015C C30000 



015F CD1400 
0162 0E1C 
0164 C30000 



;l-> addr(fcb) 
call getp2i 
mvi c,makef 
jmp ?bdos 



; . f cb to DE 

; return through bdos 



********************************************************* 

* * 
*********************************************************** 

rename: ;rename file (#23) 
; 1~> addr(fcb) 

call getp2i ;.fcb to DE 

mvi c,renamf 

jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

logvec: ; return login vector (#24) 
mvi c,loginf 

jmp ?bdos ; return through BDOS 

*********************************************************** 

* * 
*********************************************************** 

curdsk: ; return current disk number (#25) 
mvi c,cdiskf 
jmp ?bdos ; return value in A 

*********************************************************** 

* * 
*********************************************************** 

setdma: ;set DMA address (#26) 

; l-> pointer (dma address) 

call getp2 ;dma address to DE 

mvi c,setdmf 

jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

allvec: ; return address of allocation vector (#27) 
mvi c,getalf 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

wpdisk: ;write protect disk (#28) 

call chkv20 ;must be 2.0 or greater 

mvi c,wrprof 

jmp ?bdos 

*********************************************************** 

* * 
*********************************************************** 

rovec: ; return read/only vector (#29) 
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0167 CD1400 
016A 0E1D 
016C C30000 



016F CD1400 
0172 CD0600 
0175 0E1E 
0177 C30000 



017A CD1400 
017D 0E1F 
017F C30000 



0182 CD1400 

0185 1EFF 

0187 0E20 

0189 C30000 



018C CD1400 
018F CD0000 
0192 0E20 
0194 C30000 



0197 CD1400 
019A CD0600 
019D 0E21 
019F C30000 



#010 DIRECT CP/M CALLS FROM PL/I-80 

;must be 2.0 or greater 
;value returned in HL 



call chkv20 

mvi c,getrof 

jmp ?bdos 



01A2 CD1400 



*********************************************************** 

* * 
*********************************************************** 

filatt: ;set file attributes (#30) 

;l-> addr(fcb) 

call chkv20 ;must be 2.0 or greater 

call getp2i ;. fcb to DE 

mvi c,setatf 
jmp ?bdos 

************************************************** 

* * 
*********************************************************** 

getdpb: ;get base of current disk parm block (#31) 

call chkv20 ;check for 2.0 or greater 

mvi c r getdpf 

jmp ?bdos ;addr returned in HL 

*********************************************************** 

* * 
*********************************************************** 

getusr: ;get user code to register A 

call chkv20 ;check for 2.0 or greater 

mvi e,0ffh ;to get user code 

mvi c f userf 
jmp ?bdos 

*********************************************************** 

* * 
*********************************************************** 

setusr: ;set user code 

call chkv20 ;check for 2.0 or greater 

call getpl ;code to E 

mvi c,userf 
jmp ?bdos 

*********************************************************** 

* * 
*********************************************************** 

rdran: ;read random (#33) 
;l-> addr(fcb) 

call chkv20 ;check for 2.0 or greater 

call getp2i ;.fcb to DE 

mvi c,rdranf 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

wrran: ;write random (#34) 
;l-> addr(fcb) 
call chkv20 ;check for 2.0 or greater 



56 



CP/M RMAC ASSEM 0.4 

01A5 CD0 60 
01A8 0E22 
01AA C30000 



01AD CD1400 
01B0 CD0600 
01B3 0E23 
01B5 C30000 



01B8 CD1400 
01BB CD0600 
01BE 0E24 
01C0 C30000 



01C3 CD1D00 
01C6 CD0600 
01C9 0E25 
01CB C30000 



01CE CD1D00 
01D1 CD0600 
01D4 0E28 
01D6 C30000 



01D9 



#011 DIRECT CP/M CALLS FROM PL/I-80 

; .fcb to DE 
;return through bdos 



call getp2i 

mvi c,wrranf 

jmp ?bdos 



*********************************************************** 

* * 
*********************************************************** 

filsiz: ;compute file size (#35) 

call chkv20 ;must be 2.0 or greater 

call getp2 ;.fcb to DE 

mvi c,filszf 

jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

setrec: ;set random record position (#36) 

call chkv20 ;must be 2.0 or greater 

call getp2 ;.fcb to DE 

mvi c,setrcf 

jmp ?bdos ; return through bdos 

**************************************************** 

* * 
*********************************************************** 

resdrv: ; reset drive function (#37) 
;l->drive vector - bit(16) 

call chkv22 ;must be 2.2 or greater 

call getp2 ;drive reset vector to DE 

mvi c,rsdrvf 
jmp ?bdos ; return through bdos 

*********************************************************** 

* * 
*********************************************************** 

wrranz: ;write random, zero fill function 
;l-> addr(fcb) 

call chkv22 ;must be 2.2 or greater 
call getp2i ;.fcb to DE 

mvi c,wrrnzf 
jmp ?bdos 

*********************************************************** 

* * 
*********************************************************** 

end 
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CP/M RMAC ASSEM 0.4 



#012 



DIRECT CP/M CALLS FROM PL/I-80 



015A 


ALLVEC 


00E7 


BREAK 


0019 


CDISKF 


0014 


CHKV20 


001D 


CHKV22 


008C 


CHRIN 


009C 


CHROUT 


00AE 


CHRSTR 


010B 


CLOSE 


0010 


CLOSEF 


00A2 


CONINP 


00B2 


CONOUT 


000D 


CR 


014D 


CURDSK 


0079 


DBUFF 


0120 


DELETE 


0013 


DELETF 


0071 


DFCB0 


0075 


DFCB1 


0006 


DIOF 


001A 


EOF 


016F 


FILATT 


01AD 


FILSIZ 


0023 


FILSZF 


001B 


GETALF 


017A 


GETDPB 


001F 


GETDPF 


00CA 


GETIO 


0007 


GETIOF 


0000 


GETP1 


0006 


GETP2 


0006 


GETP2I 


001D 


GETROF 


0182 


GETUSR 


000C 


GETVER 


000A 


LF 


0005 


LISTF 


0018 


LOG INF 


0148 


LOGVEC 


0138 


MAKE 


0016 


MAKEF 


0054 


MEMPTR 


0058 


MEMSIZ 


0066 


MEMWDS 


0103 


OPEN 


000F 


OPENF 


0009 


PRINTF 


0004 


PUNF 


00DF 


RDBUF 


0080 


RDCON 


000A 


RDCONF 


0197 


RDRAN 


0021 


RDRANF 


008A 


RDRDR 


0003 


RDRF 


0128 


RDSEQ 


00EC 


RDSRET 


00BE 


RDSTAT 


0001 


RE ADC 


0014 


READF 


07D 


REBOOT 


0140 


RENAME 


0017 


RENAMF 


01C3 


RESDRV 


00F6 


RESET 


000D 


RESETF 


0167 


ROVEC 


0025 


RSDRVF 


0113 


SEAR 


011B 


SEARN 


000E 


SELDF 


00FB 


SELECT 


0011 


SERCHF 


0012 


SERCHN 


001E 


SETATF 


0152 


SETDMA 


001A 


SETDMF 


00CF 


SETIO 


0008 


SETIOF 


0024 


SETRCF 


01B8 


SETREC 


018C 


SETUSR 


000B 


STATF 


0020 


US ERF 


0023 


VERERR 


002E 


VERMSG 


00F1 


VERS 


000C 


VERSF 


015F 


WPDISK 


0085 


WRCON 


0002 


WRITC 


0015 


WRITF 


009A 


WRLST 


001C 


WRPROF 


0095 


WRPUN 


01A2 


WRRAN 


0022 


WRRANF 


01CE 


WRRANZ 


0028 


WRRNZF 


0130 


WRSEQ 


00D7 


WRSTR 


0000 


7BDOS 


0000 


7BEGIN 


0000 


7BOOT 


0000 


7DBUFF 


0000 


?DFCB0 


0000 


?DFCB1 
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APPENDIX B: 

LISTING OF "DIOCALLS" 
SHOWING THE BASIC CP/M DIRECT INTERFACE 
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PL/I-80 VI. 0, COMPILATION OF: DIOCALLS 



L: List Source Program 

%include •diomod.dcl' ; 
NO ERROR(S) IN PASS 1 

NO ERROR(S) IN PASS 2 



PL/I-80 VI.. 0, COMPILATION OF: DIOCALLS 



1 a 

2 a 

3 a 

4 a 
5+c 
6+c 
7+c 
8+c 
9+c 

10+c 
11+c 
12+c 
13+c 
14+c 
15+c 
16+c 
17+c 
18+c 
19+c 
20+c 
21+c 
22+c 
23+c 
24+c 

2 5+c 
26+c 
27+c 
28+c 
29+c 
30+c 
31+c 
32+c 

3 3+c 
3 4+c 

3 5+c 
36+c 
37+c 
38+c 
39+c 
40+c 
41+c 
42+c 

4 3+c 
44+c 
4 5+c 



0000 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 



diotst: 

proc options(main) ; 
/* external CP/M I/O e 
/* (note: each source 
del 



ntry points 
line begins 



*/ 

with tab chars) */ 



memptr 


entry 




returns 


(ptr) , 


memsiz 


entry 




returns 


(fixed(15)) , 


memwds 


entry 




returns 


(fixed(15)) , 


dfcb0 


entry 




returns 


(ptr) , 


dfcbl 


entry 




returns 


(ptr) , 


dbuff 


entry 




returns 


(ptr) , 


reboot 


entry, 








rdcon 


entry 




returns 


(char(l)) , 


wrcon 


entry 




(char(l) ) 


$ 


rdrdr 


entry 




returns 


(char(l)) , 


wrpun 


entry 




(char(l) ) 


F 


wrist 


entry 




(char(l) ) 


f 


coninp 


entry 




returns 


(char(l)) , 


conout 


entry 




(char(l) ) 


F 


rdstat 


entry 




returns 


(bit(l)) , 


getio 


entry 




returns 


(bit(8)) , 


setio 


entry 




(bit(8)) 


r 


wrstr 


entry 




(ptr) , 




rdbuf 


entry 




(ptr) , 




break 


entry 




returns 


(bit(l)) , 


vers 


entry 




returns 


(bit(16)) , 


reset 


entry, 








select 


entry 




(fixed(7) 


) , 


open 


entry 


(ptr) 


returns 


(fixed(7) ) , 


close 


entry 


(ptr) 


returns 


(fixed(7) ) , 


sear 


entry 


(ptr) 


returns 


(fixed(7) ) , 


searn 


entry 




returns 


(fixed(7) ) , 


delete 


entry 


(ptr) 


t 




rdseq 


entry 


(ptr) 


returns 


(fixed(7) ) , 


wrseq 


entry 


(Ptr) 


returns 


(fixed(7) ) , 


make 


entry 


(Ptr) 


returns 


(fixed(7) ) , 


rename 


entry 


(ptr) 


r 




logvec 


entry 




returns 


(bit(16)) , 


curdsk 


entry 




returns 


(fixed(7) ) , 


setdma 


entry 




(ptr) , 




allvec 


entry 




returns 


(Ptr) , 


wpd i s k 


entry, 








rovec 


entry 




returns 


(bit(16)) , 


filatt 


entry 




(ptr) , 




getdpb 


entry 




returns 


(ptr) , 
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46+c 0006 getusr entry returns (fixed(7)) r 

47+c 0006 setusr entry (f ixed(7) ) , 

48+c 0006 rdran entry (ptr) returns (£ixed(7) ) , 

49+c 0006 wrran entry (ptr) returns (fixed(7)), 

50+c 0006 f ilsiz entry (ptr) , 

51+c 0006 setrec entry (ptr), 

52+c 0006 resdrv entry (bit(16)), 

53+c 0006 wrranz entry (ptr) returns (fixed(7)); 

54 c 0006 del 

55 c 0006 c char(l) , 

56 c 0006 v char(254) var, 

57 c 0006 i fixed; 

58 c 0006 

59 c 0006 

60 c 0006 /********************************** 

61 c 0006 * * 

62 c 0006 * Fixed Location Tests: * 

63 c 0006 * MEMPTR, MEMSIZ, MEMWDS, * 

64 c 0006 * DFCB0, DFCB.1, DBUFF * 

65 c 0006 * * 

66 c 0006 **********************************/ 

67 c 0006 del 

68 c 0006 memptrv ptr, 

69 c 0006 memsizv fixed, 

70 c 0006 (dfcb0v, dfcblv, dbuffv) ptr, 

71 c 0006 command char(127) var based (dbuffv) , 

72 c 0006 1 fcb0 based(dfcb0v) , 

73 c 0006 2 drive fixed(7) , 

74 c 0006 2 name char(8) , 

75 c 0006 2 type char(3) , 

76 c 0006 2 extnt f ixed(7) , 

77 c 0006 2 space (19) bit(8), 

78 c 0006 2 cr fixed(7) , 

79 c 0006 memory (0:0) based(memptrv) bit(8) ; 

80 c 0006 memptrv = memptr(); 

81 c 000C memsizv = memsiz(); 

82 c 0012 dfcb0v = dfcb0(); 

83 c 0018 dfcblv = dfcbl () ; 

84 c 001E dbuffv = dbuff(); 

85 c 0024 put edit ('Command Tail: ', command) (a); 

86 c 004A put edit ('First Default File:', 

87 c 008D fcb0. name, '.' ,fcb0. type) (skip, 4a); 

88 c 008D put edit ('dfcb0 ' ,unspec(dfcb0v) , 

89 c 0i37 'dfcbl ' ,unspec(dfcblv) , 

90 c 0137 'dbuff ' ,unspec(dbuf fv) , 

91 c 0137 'memptr' ,unspec(memptrv) , 

92 c 0137 'memsiz' ,unspec(memsizv) , 
9 3 c 0137 'memwds* ,memwds ( ) ) 

94 c 0137 (5(skip,a(7) ,b4) ,skip,a(7) ,f (6) ) ; 

95 c 0137 put skip 1 ist (' Clear ing Memory'); 

96 c 0153 /* sample loop to clear mem */ 

97 c 0153 do i = repeat(i+l) while (i~=memsizv-l) ; 

98 c 016A memory (i) = '00' b4; 

99 c 017F end; 

100 c 017F 

101 c 017F 

102 c 017F /****«****************************** 

103 c 017F * * 

104 c 017F * REBOOT Test * 

105 c 017F * * 

61 



106 


c 


017F 


107 


c 


017F 


108 


c 


019B 


109 


c 


01B5 


110 


c 


01DD 


111 


c 


01E0 


112 


c 


01E0 


113 


c 


01E0 


114 


c 


01E0 


115 


c 


01E0 


116 


c 


01E0 


117 


c 


01E0 


118 


c 


01E0 


119 


c 


01F7 


120 


c 


0204 


121 


c 


0220 


122 


c 


2 2E 


123 


c 


022E 


124 


c 


024A 


125 


c 


0266 


126 


c 


028E 


127 


c 


028E 


128 


c 


028E 


129 


c 


028E 


130 


c 


028E 


131 


c 


028E 


132 


c 


028E 


133 


c 


028E 


134 


c 


028E 


135 


c 


2AA 


136 


c 


02C4 


137 


c 


02EC 


138 


c 


02EC 


139 


c 


0308 


140 


c 


0314 


141 


c 


0323 


142 


c 


032E 


143 


c 


033D 


144 


c 


0346 


145 


c 


0346 


146 


c 


0346 


147 


c 


0346 


148 


c 


0346 


149 


c 


0346 


150 


c 


0346 


151 


c 


0346 


152 


c 


0346 


153 


c 


0346 


154 


c 


035D 


155 


c 


0377 


156 


c 


039F 


157 


c 


03BB 


158 


c 


03E3 


159 


c 


03E3 


160 


c 


03E3 


161 


c 


03E3 


162 


c 


03E3 


163 


c 


03E3 


164 


c 


03E3 


165 


c 


03E3 



put skip list ('Reboot? (Y/N) • ) ; 
get 1 ist (c) ; 

if translated, 'Y' , 'y' ) = 'Y' then 
call reboot () ; 



* * 

* RDCON, WRCON Test * 

* * 

put list(*Type Input, End with "$" '); 
v = ' ~m~ j' ; 

do while (substr (v,length(v) ) "= *$'); 

v = v I I rdcon() ; 

end; 
put skip list('You Typed:'); 

do i = 1 to length (v); 

call wrcon(substr (v, i ,1) ) ; 

end; 



* * 

* RDRDR and WRPUN Test * 

* * 

put skip list('Reader to Punch Test? (Y/N) ') ; 
get 1 ist (c) ; 

if translated, 'Y' ,'y' ) = 'Y' then 
do; 

put skip list('Copying RDR to PUN until ctl-z'); 
C = ' '; 

do while (c ~= ' "z* ) ; 
c = rdrdr() ; 
if c ~= '"z* then 
call wrpun (c) ; 
end; 
end; 



* * 

* WRLST Test * 

* * 

put list ('Li st Output Test? (Y/N) ') ; 

get list(c) ; 

if translate(c, 'Y' ,'y' ) = 'Y' then 

do i = 1 to length (v); 

call wrist (substr (v,i ,1) ) ; 

end; 



* * 

* Direct I/O, CONOUT, CONINP * 

* * 

••••A*****************************/ 
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166 c 03E3 put list 

167 c 03FA ('Direct I/O, Type Line, End with Line Feed'); 

168 c 03FA c = ' '; 

169 c 0406 do while (c ~= '~j'); 

170 c 0415 call conout(c); 

171 c 041B c = coninpO; 

172 c 0429 end; 

173 c 0429 

174 c 0429 

175 c 0429 /********************************** 

176 c 0429 * * 

177 c 0429 * Direct I/O, Console Status * 

178 c 0429 * RDSTAT * 

179 c 0429 * * 

180 c 0429 **********************************/ 

181 c 0429 put skip list('Status Test, Type Character'); 

182 c 0445 do while (~rdstat() ) ; 

183 c 044F end; 

184 c 044F /* clear the character */ 

185 c 044F c = coninpO; 

186 c 045A 

187 c 045A 

188 c 045A /********************************** 

189 c 045A * * 

190 c 045A * GETIO, SETIO IObyte * 

191 c 045A *■ * 

192 c 045A ********************************** / 

193 c 045A del 

194 c 045A iobyte bit-(8) ; 

195 c 045A iobyte = getio(); 

196 c 0460 put edit ('IObyte is ', iobyte, 

197 c 0493 ', New Value: ') (skip, a ,b4 ,a) ; 

198 c 0493 get edit (iobyte) (b4(2)); 

199 c 04AF call setio( iobyte) ; 

200 c 04B5 

201 c 04B5 

202 c 4B5 /********************************** 

203 c 04B5 * * 

204 c 04B5 * Buffered Write, WRSTR Test * 

205 c 04B5 * * 

206 c 04B5 **********************************/ 

207 c 04B5 put list('Buffered Output Test:'); 

208 c 04CC /* "v" was previously filled by RDCON */ 

209 c 04CC call wrstr (addr (v) ) ; 

210 c 04D8 

211 c 04D8 

212 c 04D8 /********************************** 

213 c 04D8 * * 

214 c 04D8 * Buffered Read RDBUF Test * 

215 c 04D8 * * 

216 c 04D8 **********************************/ 

217 c 04D8 del 

218 c 04D8 1 inbuff static, 

219 c 04D8 2 maxsize bit(8) init( '80' b4) , 

220 c 04D8 2 inchars char(127) var; 

221 c 04D8 put skip list('Line Input, Type Line, End With Return'); 

222 c 04F4 put skip; 

223 c 0505 call rdbuf (addr ( inbuff )) ; 

224 c 0511 put skip list('You Typed: ', inchars); 

225 c 0536 
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226 


c 


0536 


227 


c 


0536 


228 


c 


0536 


229 


c 


0536 


230 


c 


0536 


231 


c 


0536 


232 


c 


0536 


233 


c 


0552 


234 


c 


055C 


235 


c 


055C 


236 


c 


0567 


237 


c 


0567 


238 


c 


0567 


239 


c 


0567 


240 


c 


0567 


241 


c 


0567 


242 


c 


0567 


243 


c 


0567 


244 


c 


0567 


245 


c 


0567 


246 


c 


56D 


247 


c 


0576 


248 


c 


0595 


249 


c 


5B1 


250 


c 


5F5 


251 


c 


5F5 


252 


c 


5F5 


253 


c 


05F5 


254 


c 


05F5 


255 


c 


05F5 


256 


c 


5F5 


257 


c 


5F5 


258 


c 


5F5 


259 


c 


0611 


260 


c 


0614 


261 


c 


0614 


262 


c 


0614 


263 


c 


0614 


264 


c 


0614 


265 


c 


0614 


266 


c 


0614 


267 


c 


0614 


268 


c 


0630 


269 


c 


0648 


270 


c 


0654 


271 


c 


654 


272 


c 


0654 


273 


c 


0654 


274 


c 


0654 


275 


c 


0654 


276 


c 


0654 


277 


c 


0654 


278 


c 


0654 


279 


c 


0654 


280 


c 


0654 


281 


c 


0654 


282 


c 


0654 


283 


c 


0654 


284 


c 


0654 


285 


c 


0654 



/••a******************************* 

* * 

* Console BREAK Test * 

* * 

put skip 1 ist( ' Console Break Test, Type Character'); 

do while(~break () ) ; 

end; 
c = rdcon() ; 



* * 

* Version Number VERS Test * 

* * 

del 

version bit(16) ; 
version = vers() ; 
if substr (version, 1 f 8) = *00'b4 then 

put skip 1 ist ( * CP/M* ) ; else 

put skip list( 'MP/M* ) ; 
put edit(' Version ' r substr (version, 9 ,4) , 

' . ' ,substr (version, 13,4) ) (a,b4 ,a ,b4) ; 



* * 

* Disk System RESET Test * 

* * 

put skip 1 ist (' Resetting Disk System'); 
call reset() ; 



* * 

* Disk SELECT Test * 

* * 

put skip list('Select Disk # '); 
get 1 ist (i) ; 
call select(i) ; 

* * 

* Note: The OPEN, CLOSE, SEAR, * 

* SEARN, DELETE, RDSEQ, * 

* WRSEQ, MAKE, and RENAME * 

* functions are tested in the * 

* DIOCOPY program * 

* * 

* * 

* LOGVEC and CURDSK * 
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286 


c 


0654 


287 


c 


0695 


288 


c 


0695 


289 


c 


0695 


290 


c 


0695 


291 


c 


0695 


292 


c 


0695 


293 


c 


0695 


294 


c 


0695 


295 


c 


0695 


296 


c 


0695 


297 


c 


0695 


298 


c 


0695 


299 


c 


0695 


300 


c 


0695 


301 


c 


0695 


302 


c 


0695 


303 


c 


0695 


304 


c 


0695 


305 


c 


0695 


306 


c 


069B 


307 


c 


0700 


308 


c 


0700 


309 


c 


0700 


310 


c 


0700 


311 


c 


7 


312 


c 


0700 


313 


c 


0700 


314 


c 


0700 


315 


c 


0700 


316 


c 


0700 


317 


c 


0700 


318 


c 


0700 


319 


c 


0700 


320 


c 


0700 


321 


c 


0700 


322 


c 


0700 


323 


c 


0700 


324 


c 


071C 


325 


c 


0736 


326 


c 


075E 


327 


c 


0761 


328 


c 


0761 


329 


c 


0761 


330 


c 


0761 


331 


c 


0761 


332 


c 


0761 


333 


c 


0761 


334 


c 


0788 


335 


c 


0788 


336 


c 


0788 


337 


c 


0788 


338 


c 


0788 


339 


c 


0788 


340 


c 


0788 


341 


c 


0788 


342 


c 


0788 


343 


c 


0788 


344 


c 


0788 


345 


c 


0788 



put skip list ('Login Vector' , 
logvec() , 'Current Disk' , 
curdsk () ) ; 

* * 

* See DIOCOPY for SETDMA Function * 

* * 

* Allocate Vector ALLVEC Test * 

del 

alloc (0:30) bit(8) 
based (allvec() ) , 

allvecp ptr; 
allvecp = allvec(); 
put edit('Alloc Vector at * , 

unspec( allvecp) , * : ' , 

(alloc(i) do i=0 to 30)) 

(skip,a,b4,a,2 54 (skip, 4 (b,x(l) ) ) ) ; 

* * 

* Note: the following functions * 

* apply to version 2.0 or newer. * 

* * 

* * 

* WPDISK Test * 

* * 

put skip list('Write Protect Disk? (Y/N) • ) ; 
get 1 ist (c) ; 

if translated, 'Y' ,' y' ) = 'Y' then 
call wpdisk() ; 

* * 

* ROVEC Test * 

* * 

put skip 1 ist ( 'Read/Only Vector is' ,rovec () ) ; 

* * 

* Disk Parameter Block Decoding * 

* Using GETDPB * 

* * 

del 

dpbp ptr, 

1 dpb based (dpbp) , 

2 spt f ixed(15) , 

2 bsh f ixed(7) , 
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346 


c 


0788 


347 


c 


0788 


348 


c 


0788 


349 


c 


0788 


350 


c 


0788 


351 


c 


0788 


352 


c 


0788 


353 


c 


0788 


354 


c 


0788 


355 


c 


078E 


356 


c 


08C6 


357 


c 


08C6 


358 


c 


08C6 


359 


c 


08C6 


360 


c 


08C6 


361 


c 


08C6 


362 


c 


08C6 


363 


c 


08C6 


364 


c 


08C6 


365 


c 


08C6 


366 


c 


08C6 


367 


c 


08C6 


368 


c 


8C6 


369 


c 


08C6 


370 


c 


08C6 


371 


c 


03C6 


372 


c 


08C6 


373 


c 


08FC 


374 


c 


08FC i 


375 


c 


0914 


376 


c 


0920 


377 


c 


0920 


378 


c 


0920 


379 


c 


0920 


380 


c 


0920 


381 


c 


0920 


382 


c 


0920 


383 


c 


0920 


384 


c 


0920 


385 


c 


0920 


386 


c 


0920 


387 


c 


0920 


388 


c 


0920 


389 


c 


0920 


390 


c 


0920 


391 


c 


0920 i 


392 


c 


0920 


393 


c 


0920 i 


394 


c 


0937 < 


395 


c 


094F 


396 


c 


0955 


397 


c 


0955 


398 


c 


0955 


399 


c 


0955 


400 


c 


0955 


401 


a 


0955 


CODE 


SIZE = 0958 


DATA 


AREA = 04BA 



2 blm bit(8) , 
2 exm bit(8) , 
2 dsm bit(16) , 
2 drm bit(16) , 
2 al0 bit(8) , 
2 all bit(8) , 
2 cks bit(16) , 
2 off fixed(7) ; 
dpbp = getdpb() ; 

put edit('Disk Parameter Block:' , 
' spt' f spt, ' bsh' ,bsh, ' blm* ,blm r 
* exm' ,exm, * dsm* ,dsm, ' drm' ,drm, 
'al0' ,al0 f 'all* ,311, 'cks' ,cks, 
•off ,off) 

(skip, a, 2 (skip, a (4) ,f (6) ) , 
4(skip,a(4) ,b4) , 
skip,2(a(4) ,b,x(l)) , 
skip, a (4) ,b4, 
skip,a(4) ,f (6)); 

/********************************** 

* * 

* Test Get/Set user Code * 

* GETUSR, SETUSR * 

* * 

put skip list 

('User is' ,qetusr() , ' , New User: 1 ); 
qet list(i) ; 
call setusr(i) ; 

/********************************** 

* * 

* FILSIZ, SETREC, * 

* RDRAN, WRRAN, WRRANZ are * 

* tested in DIORAND * 

* * 

it*********************************/ 

/********************************** 

* * 

* Test Drive Reset RESDRV * 

* (version 2.2 or newer) * 

* * 

**********************************/ 
del 

drvect bit(16) ; 
put list('Drive Reset Vector:'); 
get list(drvect) ; 
call resdrv(drvect) ; 

* * 

* * 

end diotst; 
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APPENDIX C: 

LISTING OF "DIOCOPY" 
SHOWING DIRECT CP/M FILE I/O OPERATIONS 
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PL/I-80 VI. 0, COMPILATION OF: DIOCOPY 



L: List Source Program 



%include 
%include 
%include 
%include 
%include 



'diomod.dcl' ; 
•fcb.dcl' 
•fcb.dcl' 
' fcb.dcl' 
•fcb.dcl' 



NO ERROR(S) IN PASS 1 
NO ERROR(S) IN PASS 2 



PL/I-80 VI. 0, COMPILATION OF: DIOCOPY 



1 a 


0000 


diocopy 


• 












2 a 


0006 


proc options(main) ; 










3 a 


0006 


/* 


file to 


file copy p 


ro 


gram */ 




4 a 


0006 


/* 


(all source lines b 


eg 


in with tabs) */ 


5 a 


0006 
















6 c 


0006 


%replace 












7 c 


0006 




bufwds 


by 64 r 


/* 


words per \ 


Duffer */ 


8 c 


0006 




quest 


by 63, 


/* 


ASCII '?' " 


V 


9 c 


0006 




true 


by 'l'b, 










10 c 


0006 




false 


by '0'b; 










11 c 


0006 
















12+c 


0006 


del 














13+c 


0006 




memptr 


entry 






returns 


(ptr) , 


14+c 


0006 




memsiz 


entry 






returns 


(fixed(15) ) , 


15+c 


0006 




memwds 


entry 






returns 


(fixed(15) ) , 


16+c 


0006 




dfcb0 


entry 






returns 


(ptr) , 


17+c 


0006 




dfcbl 


entry 






returns 


(ptr) , 


18+c 


0006 




dbuff 


entry 






returns 


(Ptr) , 


19+c 


0006 




reboot 


entry, 










20+c 


0006 




rdcon 


entry 






returns 


(char(l)) , 


21+c 


0006 




wrcon 


entry 






(char(l) 


' r 


2 2+c 


0006 




rdrdr 


entry 






returns 


(char(l)) , 


2 3+c 


0006 




wrpun 


entry 






(char(l) 


' t 


2 4+c 


0006 




wrist 


entry 






(char(l) 


) t 


2 5+c 


0006 




coninp 


entry 






returns 


(char(l)) , 


26+c 


0006 




conout 


entry 






(char(l) 


' t 


27+c 


0006 




rdstat 


entry 






returns 


(bit(l)) , 


28+c 


0006 




getio 


entry 






returns 


(bit(8)) , 


29+c 


0006 




setio 


entry 






(bit(8)) 


r 


30+c 


0006 




wrstr 


entry 






(ptr) , 




31+c 


0006 




rdbuf 


entry 






(Ptr) , 




3 2+c 


0006 




break 


entry 






returns 


(bit(l)) , 


3 3+c 


0006 




vers 


entry 






returns 


(bit(16)) , 


34+c 


0006 




reset 


entry, 










3 5+c 


0006 




select 


entry 






(fixed^ 


>) , 


36+c 


0006 




open 


entry 


(Pt 


r) 


returns 


(fixed(7) ) , 


37+c 


0006 




close 


entry 


(Pt 


r) 


returns 


(fixed(7)) , 


38+c 


0006 




sear 


entry 


(Pt 


r) 


returns 


(fixed(7)) , 


39+c 


0006 




searn 


entry 






returns 


(fixed(7)), 


40+c 


0006 




delete 


entry 


(Pt 


r) 


F 




41+c 


0006 




rdseq 


entry 
68 


(Pt 


r) 


returns 


(fixed(7)) , 



42+c 
4 3+c 
44+c 
4 5+c 
46+c 
47+c 
48+c 
49+c 
50+c 
51+c 
52+c 
53+c 
54+c 
55+c 
56+c 
57+c 
58+c 
59+c 
60+c 

61 c 

62 c 

63 c 
64+c 
65+c 
66+c 
67+c 
68+c 
69+c 
7 0+c 
71+c 
7 2+c 
73+c 
74+c 
7 5+c 
7 6+c 
77+c 
7 8+c 

79 c 

80 c 

81 c 

82 c 
83+c 
84 + c 
85+c 
86+c 
87 + c 
88+c 
89+c 
90+c 
91+c 
9 2+c 
9 3+c 
9 4+c 
9 5+c 
96+c 
97+c 

98 c 

99 c 
100 c 
101+c 



0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 



del 



del 



del 



wrseq 


entry 


(ptr) 


returns 


[fixed (7)) , 


make 


entry 


(ptr) 


r e t ur ns 


(fixed(7) ) , 


rename 


entry 


(ptr) 


i 




logvec 


entry 




returns 


(bit(16)) , 


curdsk 


entry 




returns 


(fixed(7) ) , 


setdma 


entry 




(ptr) , 




a 1 1 ve c 


entry 




returns 


[ptr) , 


wpdisk 


entry, 








rovec 


entry 




returns 


(bit(16) ) , 


f ilatt 


entry 




(ptr) , 




qetdpb 


entry 




returns 


(ptr) , 


getusr 


entry 




returns 


(fixed(7) ) , 


se tusr 


entry 


(fixe 


d(7)) , 




rdran 


entry 


(Ptr) 


returns 


(fixed(7) ) , 


wrran 


entry 


(Ptr) 


returns 


(fixed(7) ) , 


f ilsiz 


entry 


(Ptr) 


r 




setrec 


entry 


(ptr) 


t 




resdrv 


entry 




(bit(16) ) 


r 


wrranz 


entry 


(ptr) 


returns 


(fixed(7) ) ; 



/* 
/* 
/* 
/* 



destf ile, 
2 namel, 

3 drive fixed(7) 
3 fname char(8) , 
3 ftype char(3) , 
3 fext fixed(7) . 
3 space (3) bit(8) ,/* 
2 name2, /* 

3 drive2 fixed(7) , 
3 fname2 char(8) , 
3 ftype2 char(3) , 
3 fext2 fixed(7) , 
3 space2 (3) bit(8) , 
2 crec f ixed(7) , /* 
2 rrec fixed(15) , /* 
2 rovf f ixed(7) ; /* 



drive number */ 
file name */ 
file type */ 
file extent */ 
filler */ 
used in rename */ 



current record */ 
random record */ 
random rec overflow 



3 

3 

3 

3 

crec 

rrec 



/* 
/* 
/* 
/* 



dfcb0p ptr, 

1 sourcefile based(dfcb0p) 
2 namel, 

3 drive f ixed(7) , 
fname char (8) , 
ftype char(3) , 
fext fixed(7) , 
space (3) bit(8) ,/* 
name2, /* 

3 drive2 f ixed(7) , 
f name2 char (8) , 
ftype2 char(3) , 
fext2 fixed(7) , 
space2 (3) bit(8) , 
fixed(7) , /* 
fixed(15) , /* 



rovf fixed(7) 



/ 



/ 



drive number */ 
file name */ 
file type */ 
file extent */ 
filler */ 
used in rename i 



current record */ 
random record */ 
random rec overflow 



'/ 



dfcblfile based(dfcbK) ) 
2 namel, 
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102+c 0006 3 drive fixed(7) , /* drive number */ 

103+c 0006 3 fname char(8) , /* file name */ 

104+c 0006 3 ftype char(3) , /* file type */ 

105+c 0006 3 fext fixed(7) , /* file extent */ 

106+c 0006 3 space (3) bit(8),/* filler */ 

107+c 0006 2 name2, /* used in rename */ 

108+c 0006 3 drive2 f ixed(7) , 

109+c 0006 3 fname2 char(8) , 

110+c 0006 3 f type2 char(3) , 

111+c 0006 3 fext2 fixed(7), 

112+c 0006 3 space2 (3) bit(8) , 

113+c 0006 2 crec fixed(7) , /* current record */ 

114+c 0006 2 rrec fixed(15) , /* random record */ 

115+c 0006 2 rovf f ixed(7) ; /* random rec overflow */ 

116 c 0006 

117 c 0006 del 

118 c 0006 1 renfile, 
119+c 0006 2 namel, 

120+c 0006 3 drive fixed(7) , /* drive number */ 

121+c 0006 3 fname char(8) , /* file name */ 

122+c 0006 3 ftype char(3) , /* file type */ 

123+c 0006 3 fext fixed(7), /* file extent */ 

124+c 0006 3 space (3) bit(8) ,/* filler */ 

125+c 0006 2 name2, /* used in rename */ 

126+c 0006 3 drive2 f ixed(7) , 

127+c 0006 3 fname2 char(8) , 

128+c 0006 3 ftype2 char(3) r 

129+c 0006 3 fext2 fixed(7) , 

130+c 0006 3 space2 (3) bit(8) , 

131+c 0006 2 crec fixed(7) , /* current record */ 

132+c 0006 2 rrec fixed(15), /* random record */ 

133+c 0006 2 rovf fixed(7); /* random rec overflow */ 

134 c 0006 

135 c 0006 del 

136 c 0006 answer char(l) , 

137 c 0006 extent fixed(7) ; 

138 c 0006 

139 c 0006 del 

140 c 0006 /* buffer management */ 

141 c 0006 eofile bit(8) , 

142 c 0006 i fixed(15) , 

143 c 0006 m fixed(15) , 

144 c 0006 nbuffs fixed(15), 

145 c 0006 memory (0:0) bit(16) based(memptr () ) ; 

146 c 0006 

147 c 0006 /* compute number of buffs, 64 words each */ 

148 c 0006 nbuffs = divide (memwds () ,bufwds, 15) ; 

149 c 0017 if nbuffs = then 

150 c 0020 do; 

15.1 c 0020 put skip list('No Buffer Space'); 

152 c 003C call reboot() ; 

153 c 003F end; 

154 c 003F 

155 c 003F /* initialize feb's */ 

156 c 003F dfcb0p = dfcb0(); 

157 c 0045 destfile = dfcblfile; 

158 c 0054 

159 c 0054 /* copy feb to rename file, count extents */ 

160 c 0054 renfile = destfile; 

161 c 0060 /* search all extents by inserting '?' */ 
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162 


c 


0060 


163 


c 


0065 


164 


c 


0076 


165 


c 


0076 


166 


c 


07B 


167 


c 


3083 


168 


c 


008A 


169 


c 


008A 


170 


c 


00C1 


171 


c 


00C1 


172 


c 


00C1 


173 


c 


0DB 


174 


c 


00FF 


175 


c 


0102 


176 


c 


0102 


177 


c 


0102 


178 


c 


0102 


179 


c 


010E 


180 


c 


010E 


181 


c 


011A 


182 


c 


011A 


183 


c 


011A 


184 


c 


012B 


185 


c 


012B 


186 


c 


0147 


187 


c 


014A 


188 


c 


014A 


189 


c 


014A 


190 


c 


014A 


191 


c 


014F 


192 


c 


0154 


193 


c 


0165 


194 


c 


0165 


195 


c 


0181 


196 


c 


0184 


197 


c 


0184 


198 


c 


0184 


199 


c 


0184 


200 


c 


0189 


201 


c 


0190 


202 


c 


0196 


203 


c 


0196 


204 


c 


01A6 


205 


c 


01B9 


206 


c 


01C3 


207 


c 


01D4 


208 


c 


01D4 


209 


c 


01D9 


210 


c 


01D9 


211 


c 


01E9 


212 


c 


01E9 


213 


c 


01E9 


214 


c 


01EF 


215 


c 


01EF 


216 


c 


0206 


217 


c 


0219 


218 


c 


0223 


219 


c 


0234 


220 


c 


0234 


221 


c 


0250 



renfile.fext = quest; 
if sear (addr(renf ile) ) ~= -1 then 
do; 
extent = 1; 

do while(searn() ~= -1); 

extent = extent + 1; 

end; 
put edit 

('OK to Delete ', extent, ' Extent(s) ? (Y/N) • ) 

(skip, a, f (3) f a) ; 
get 1 ist (answer) ; 
if ~ (answer = *Y' ! answer = 'y') then 

call rebootO ; 
end; 

/* destination file will be deleted later */ 

destfile.ftype = '$$$'; 

/* delete any existing x.$$$ file */ 

call delete(addr(destf ile) ) ; 

/* open the source file, if possible */ 
if open(addr(sourcef ile) ) = -1 then 

do; 

put skip list('No Source File'); 

call rebootO ; 

end; 

/* source file opened, create $$$ file */ 

destf ile. f ext = 0; 

destf ile.crec = 0; 

if make (addr(destf ile) ) = -1 then 

do; 

put skip list('No Directory Space'); 

call rebootO ; 

end; 

/* $$$ temp file created, now copy from source */ 
eofile = false; 

do while ("eofile) ; 
m = ; 

/* fill buffers */ 

do i = repeat (i+1) while (i<nbuffs); 
call setdma (addr(memory(m) )) ; 
m = m + bufwds; 

if rdseq(addr ( sourcef ile) ) ~= then 
do; 

eofile = true; 
/* truncate buffer */ 
nbuffs = i; 
end; 
end; 
m = 0; 

/* write buffers */ 
do i = to nbuffs-1; 
call setdma (addr(memory(m) )) ; 
m = m + bufwds; 

if wrseq(addr(destf ile) ) ~= then 
do; 

put skip list('Disk Full'); 
call rebootO ; 
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222 


c 


0260 


223 


c 


0260 


2 24 


c 


0260 


225 


c 


0260 


226 


c 


0260 


227 


c 


0260 


228 


c 


0271 


229 


c 


0271 


230 


c 


28D 


231 


c 


0290 


232 


c 


0290 


233 


c 


0290 


234 


c 


0290 


235 


c 


29C 


236 


c 


029C 


237 


c 


029C 


238 


c 


2AB 


239 


c 


02B7 


240 


a 


02BA 



end; 
end; 
end; 

/* close destination file and rename */ 
if close(addr(destf ile) ) = -1 then 

do; 

put skip list('Disk R/0'); 

call reboot() ; 

end; 

/* destination file closed, erase old file */ 
call delete(addr( renf ile) ) ; 

/* now rename $$$ file to old file name */ 
destf ile.name2 = renf il e.namel; 
call rename(addr(destf ile) ) ; 
call reboot () ; 
end diocopy; 



CODE SIZE = 02BD 
DATA AREA = 00EF 
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APPENDIX D: 

LISTING OF "DIORAND" 
SHOWING EXTENDED RANDOM ACCESS CALLS 
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PL/I-80 VI. 0, COMPILATION OF: DIORAND 



L: List Source Program 

%include 'diomod.dcl' ; 
%include ' fcb.dcl'; 

NO ERROR(S) IN PASS 1 

NO ERROR(S) IN PASS 2 



PL/I-80. VI. 0, COMPILATION OF: DIORAND 



1 a 

2 a 

3 a 

4 a 
5+c 
6+c 
7+c 
8+c 
9+c 

10+c 
11+c 
12+c 
13+c 
14+c 
15+c 
16+c 
17+c 
18+c 
19+c 
20+c 
21+c 
2 2+c 
23+c 
24+c 

2 5+c 
26+c 
27+c 
28+c 
29+c 
30+c 
31+c 
32+c 

3 3+c 
34+c 

3 5+c 
36+c 
37+c 
38+c 
39+c 
40+c 
41+c 
42+c 
43+c 

4 4+c 



0000 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 
0006 



diorand: 

proc options(main) ; 

/* random access tests for 2.0 and 2.2 */ 



del 



memptr 

memsiz 

memwds 

dfcb0 

dfcbl 

dbuff 

reboot 

rdcon 

wrcon 

rdrdr 

wrpun 

wrist 

coninp 

conout 

rdstat 

getio 

setio 

wrstr 

rdbuf 

break 

vers 

reset 

select 

open 

close 

sear 

searn 

delete 

rdseq 

wrseq 

make 

rename 

logvec 

curdsk 

setdma 

allvec 

wpdisk 

rovec 

filatt 



entry 

entry 

entry 

entry 

entry 

entry 

entry, 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry, 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry 

entry, 

entry 

entry 
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(ptr) 
(Ptr) 
(ptr) 

(ptr) 
(ptr) 
(Ptr) 
(Ptr) 
(Ptr) 



returns 
returns 
returns 
returns 
returns 
returns 

returns 

(char(l) 

returns 

(char(l) 

(char(l) 

returns 

(char(l) 

returns 

returns 

(bit(8)) 

(ptr) , 

(ptr) , 

returns 

returns 

(fixed(7 

returns 

returns 

returns 

returns 

returns 
returns 
returns 

returns 
returns 
(ptr) , 
returns 

returns 
(ptr) , 



Ptr) , 

fixed(15) ) , 
fixed(15) ) , 
ptr) , 
Ptr) , 
Ptr) , 

char(l)) , 

char(l)) , 



char(l) ) 

bit(l)) , 
bit(8)), 



bit(l)) , 
bit(16)) , 

), 

fixed(7) ) , 
fixed(7) ) , 
fixed(7) ) , 
fixed(7) ) , 

fixed(7) ) , 
fixed(7) ) , 
fixed(7) ) , 

bit(16)), 
f ixed(7) ) , 

Ptr) , 
bit(16)) , 



45+c 


0006 


4 6+c 


0006 


4 7+c 


0006 


48+c 


0006 


49+c 


0006 


50+c 


0006 


51+c 


0006 


5 2+c 


0006 


53+c 


0006 


54 c 


0006 


55 c 


0006 


56 c 


0006 


57+c 


0006 


58+c 


0006 


59+c 


0006 


60+c 


0006 


61+c 


0006 


62+c 


0006 


63+c 


0006 


64+c 


0006 


65+c 


0006 


66+c 


0006 


67+c 


0006 


68+c 


0006 


69+c 


0006 


70+c 


0006 


71+c 


0006 


72 c 


0006 


73 c 


0006 


74 c 


0006 


75 c 


0006 


76 c 


0006 


77 c 


0006 


78 c 


0006 


79 c 


0006 


80 c 


0006 


81 c 


0006 


82 c 


0006 


83 c 


0006 


84 c 


0006 


85 c 


0006 


86 c 


0006 


87 c 


0006 


88 c 


0006 


89 c 


0006 


90 c 


0006 


91 c 


0006 


92 c 


0006 


93 c 


0006 


94 c 


0006 


95 c 


0022 


96 c 


0022 


97 c 


0028 


98 c 


0031 


99 c 


0031 


100 c 


004D 


101 c 


0050 


102 c 


0050 


103 c 


006C 


104 c 


0086 



del 



del 



del 



getdpb entry returns (ptr) , 

qetusr entry returns (fixed(7)) 

setusr entry (fixed(7)), 

rdran entry (ptr) returns (fixed(7)) 

wrran entry (ptr) returns (fixed(7)) 

filsiz entry (ptr) 

setrec entry (ptr) 



* 



i 



resdrv entry (bit(16) ) , 

wrranz entry (ptr) returns (fixed(7)); 



database, 
2 namel, 

3 drive f ixed(7) , /* drive number */ 

3 fname char(8), /* file name */ 

3 f type char(3) , /* file type */ 

3 fext fixed(7), /* file extent */ 

3 space (3) bit(8),/* filler */ 
2 name2 f /* used in rename */ 

3 drive2 f ixed(7) , 

3 fname2 char(8) , 

3 ftype2 char(3) , 

3 fext2 f ixed(7) , 

3 space2 (3) bit(8) , 
2 crec fixed(7) , /* current record */ 
2 rrec fixed(15) , /* random record */ 
2 rovf f ixed(7) ; /* random rec overflow */ 



lower char(26) static initial 
( ' abedefghi jklmnopqrstuvwxyz' ) , 
upper char(26) static initial 
( ' ABCDEFGHIJKLMNOPQRSTUVWXYZ ' ) ; 



/ 



/* sirr 


ipl 


e variables 


i 




fixed, 


fn 




char (20) , 


c 




char (1) , 


code 




fixed(7) r 


mode 




fixed(2) , 



zerofill bit(l) , 
version bit(16) ; 

del 

/* overlays on default buffer */ 
bitbuf (128) bit(8) based(dbuf f () ) , 
buffer char(127) var based(dbuff ( ) ) ; 

put skip list('Random Access Test'); 
/* check version number for 2.0 */ 
version = vers() ; 
if substr(version,9,8) < *20'b4 then 

do; 

put skip list('You Need Version 2'); 

stop; 

end; 
put skip list('Zero Record Fill?*); 
get 1 ist (c) ; 
zerofill = (c = 'Y' I c = 'y 1 ) & 
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105 


c 


00B5 


106 


c 


00B5 


107 


c 


00B5 


108 


c 


00B5 


109 


c 


0D1 


110 


c 


00EB 


111 


c 


0110 


112 


c 


0110 


113 


c 


0110 


114 


c 


0120 


115 


c 


0129 


116 


c 


0131 


117 


c 


0131 


118 


c 


013B 


119 


c 


0L3B 


120 


c 


013B 


121 


c 


0153 


122 


c 


016C 


123 


c 


016C 


124 


c 


0188 


125 


c 


018B 


126 


c 


018B 


127 


c 


01A4 


128 


c 


01A4 


129 


c 


01A4 


130 


c 


01A4 


131 


c 


01B4 


132 


c 


01BD 


133 


c 


01BD 


134 


c 


01BD 


135 


c 


01CA 


136 


c 


01D9 


137 


c 


01D9 


138 


c 


01D9 


139 


c 


01D9 


140 


c 


01F5 


141 


o 


020F 


142 


c 


020F 


143 


n 


020F 


144 


c 


020F 


145 


c 


0214 


146 


c 


0214 


147 


c 


0225 


148 


c 


0225 


149 


c 


0241 


150 


c 


0252 


151 


c 


0252 


152 


c 


026E 


153 


c 


0274 


154 


c 


0274 


155 


c 


0274 


156 


c 


0274 


157 


c 


0274 


158 


c 


0280 


159 


c 


2B2 


160 


c 


2B2 


161 


c 


2B2 


162 


c 


2B2 


163 


c 


2B2 


164 


c 


02BE 



substr(version,9,8) >= '22'b4; 

/* read and process file name */ 
put skip list('Data Base Name: *); 
get 1 ist (f n) ; 
fn = translate(fn, upper, lower) ; 

/* process optional drive prefix */ 
i = index(fn, ' : ' ) ; 
if i = then 
drive = 0; 
else 

if i = 2 then 
do; 

/* convert character to drive code */ 
drive = index(upper,substr (fn, 1,1) ) ; 
if drive = i drive > 16 then 
do; 

put skip list('Bad Drive Name'); 
stop; 
end; 
fn = substr (fn, i+1) ; 
end; 

/* get file name and optional type */ 
i = index( fn, ' . ' ) ; 
if i = then 

do; 

/* no file type specified, use .DAT */ 

fname = fn; 

f type = ' DAT' ; 

end; 
else 

do; 

fname = substr ( fn, 1 , i-1 ) ; 

ftype = substr ( fn, i+1 ) ; 

end; 

/* clear the extent field */ 
fext =0; 

if open(addr(database) ) = -1 then 
do; 

put skip 1 ist( 'Creating New Database*); 
if make (addr(database) ) = -1 then 

do; 

put skip list('No Directory Space'); 

stop; 

end; 
end; 
else 

do; 

call f ilsiz (addr(database) ) ; 

put skip list('File Size : ' ,rrec, ' Records'); 

end; 

/* main processing loop */ 
do while('l'b) ; 
call setrec(addr(database) ) ; 
put skip list( 'Current Record' ,rrec) ; 
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165 c 02E5 put skip 1 ist ( ' Read(0) , Wr i te (1) ,Qui t (2) ? '); 

166 c 0301 get list(mode); 

167 c 031A if mode < 2 then 

168 c 0322 do; 

169 c 0322 put skip list('Record Number? ' ); 

170 c 033E get list(rrec); 

171 c 035B rovf = 0; 

172 c 0360 end; 

173 c 0360 if mode = then 

174 c 0367 do; 

175 c 0367 code = rdran(addr (database) ) ; 

176 c 0376 if code = then 

177 c 037D do; 

178 c 037D if bitbuf(l) = '00'b4 then 

179 c 0386 put skip list('Zero Record'); 

180 c 03A5 else 

181 c 03A5 put skip 1 ist (buff er) ; 

182 c 03C2 end; 

183 c 03C2 else 

184 c 03C2 put skip list('Return Code' ,code) ; 

185 c 03F0 end; 

186 c 03F0 else 

187 c 03F0 if mode = 1 then 

188 c 3F7 do; 

189 c 3F7 put skip list ('Data: •); 

190 c 0413 get 1 ist(buf f er) ; 

191 c 042F if zerofill then 

192 c 0436 code = wrranz (addr (database) ) ; 

193 c 0448 else 

194 c 0448 code = wrran (addr (database) ) ; 

195 c 0457 if code *- then 

19* c 11 C E put skip list(' Return Code' ,code) ; 

197 c 048C end; 

198 c 048C else 

199 c 048C if mode = 2 then 

200 c 0494 do; 

201 c 0494 if close(addr(database) ) = -1 then 

202 c 04A5 put skip 1 ist (' Read/Only ') ; 

203 c 04C1 stop; 

204 c 04C7 end; 

205 c 04C7 end; 

206 a 04C7 end diorand; 

CODE SIZE = 04C7 
DATA AREA = 018 3 



77 



APPENDIX E 
OVERLAYS AND FILE LOCATION CONTROLS 



This appendix describes several additional features incorporated 
into LINK-80 and LIB-80 in release versions later than 1.0, including 
extensions to process run-time overlays, and controls for location of 
source, intermediate, and destination files. Use of the automatic 
PL/I-80 library search "request item" is included, along with a 
description of new command line error reporting formats. Additional 
LIB-80 facilities are also included for deleting or replacing various 
modules in a subprogram library. 



E . 1 . . OVERLAYS 

LINK may be used to produce a simple tree structure of overlays 
as shown in the diagram below: 



OV5 OV6 



OV1 OV2 OV3 OV4 



ROOT 



In addition to producing ROOT.COM and R00T.SYM files, LINK will 
produce an OVL file and a SYM file for each overlay specified in the 
command line. The OVL file consists of a 256-byte header containing 
the load address and length of the overlay, followed by the absolute 
object code. The origin of an overlay is the highest address of the 
module below it on the 'tree' rounded up to the next 128-byte 
boundary. The stack and free space for the PL/I program will be 
located at the top of the highest overlay linked, rounded up to the 
next 128-byte boundary. This address is written to the console upon 
completion of the entire link and is patched into the root module in 
the location '?MEMRY'. The SYM file contains only those symbols which 
have not been declared in another module lower in the 'tree'. 

The following restrictions must be observed when producing a 
system of overlays with PL/I-80 and LINK: 
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Each overlay has one entry point by which it is entered. This 
entry point is assumed by the overlay manager to be at the base 
(load address) of the overlay. 

No upward references are allowed from a module to an entry point 
in an overlay higher on the tree, other than the main entry 
point of the overlay as described in 1. Downward references to 
entry points in overlays lower on the tree or in the root module 
are allowed. 

The overlays are not relocatable. Hence the root module must be 
a COM file. 

Common blocks (Externals in PL/I) which are declared in one 
module may not be initialized by a module higher in the tree. 
Any attempt to do so will be ignored by LINK. 

Overlays may be nested to a depth of 5 levels. 

The default buffer located at 80H is used by the overlay 
manager, so user programs should not depend on data stored in 
this buffer. 



E.l.l. USING OVERLAYS IN PL/I PROGRAMS 

There are two ways to use overlays in a PL/I program. The first 
method is very straightforward, and will suffice for most 
applications. However, it has the restrictions that all overlays must 
be on the default drive, and overlay names may not be determined at 
run-time. The second method does not have these restrictions, and 
involves a slightly more complicated calling sequence. 

To use the first method, an overlay is simply declared as an 
entry constant in the module where it is referenced. As an entry 
constant, it may have parameters declared in a parameter list. The 
overlay itself is simply a PL/I procedure, or group of procedures. 
For example, the following program is a root module having one 
overlay: 

root: procedure options (main) ; 
declare ovl entry (char (15)); 
put skip list ('root') ; 
call ovl ('overlay 1'); 
end root; 

The overlay 0V1.PLI appears as follows: 
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ovl: procedure (c) ; 
declare c char (15) ; 
put skip list (c) ; 
end ovl; 

Note that if parameters are passed to an overlay, it is the 
programmer's responsibility to ensure that the number and type of the 
parameters are the same in the calling program and the overlay itself. 

To link these two programs into an overlay system, the following 
link command would be used: 

LINK ROOT(OVl) 

(The command line syntax for linking overlays is described in detail 
in a later section.) 

LINK will produce four files from this command: R00T.COM, 
ROOT.SYM, 0V1.0VL and 0V1.SYM. When R00T.COM is executed, it will 
first put the message 'root' out at the console. The 'call ovl' 
statement will transfer control to the overlay manager. The overlay 
manager loads the file 0V1.0VL from the default drive at the proper 
location above R00T.COM and transfers control to it, passing the char 
(15) parameter in the normal manner. The overlay then executes, 
producing the message 'overlay 1' at the console. It then returns 
directly to the statement following the 'call ovl' in root.pli, and 
execution continues from that point. 

Using this method, if the overlay manager determines that the 
requested overlay is already in memory, the overlay will not be 
reloaded before control is transferred to it. There are several 
important notes regarding this first overlay method: 

The name associated with the overlay in the call and entry 
statements is the actual name of the OVL file loaded by the 
overlay manager, so the two names must agree. Since symbol 
names are truncated to 6 characters in the REL file produced by 
PL/I-80, the names of the OVL files must be limited to 6 
characters. 

The name of the entry point to an overlay (the name of the 
procedure) need not agree with the name used in the calling 
sequence. The same name should be used to avoid confusion. 

The overlay manager will only load overlays from the default 
drive (the drive which was the default drive when execution of 
the root module began, regardless of any changes to the default 
drive which may have occurred since then) . 

The names of the overlays are fixed - the source program must be 
edited, recompiled and relinked to change the names of the 
overlays. 
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No non-standard PL/I statements are needed (the program is 
transportable to other systems) . 

In some applications it is useful to have greater flexibility 
with overlays, such as the ability to load overlays from different 
drives, or the ability to determine the name of an overlay at 
run-time, say from the keyboard or from a disk file. This is 
accomplished using a second overlay method. 

In this case, an explicit entry point into the overlay manager 
must be declared in the PL/I program as follows: 

declare ?ovlay entry (char (10), fixed (1)); 

The first parameter is a character string specifying the name of the 
overlay to load and an optional drive code in the standard CP/M format 
'd:f ilename' . The second parameter is the load flag. If the load 
flag is 1, the overlay manager will load the specified overlay whether 
or not it is already in memory. If the load flag is 0, the overlay 
will only be loaded if it is not already in memory. 

The 'call ?ovlay' statement tells the overlay manager to load 
the requested overlay, if needed. The overlay manager returns to the 
calling program, which must then perform a dummy call to execute the 
overlay just processed by the overlay manager. This allows a 
parameter list to be passed to the overlay. 

The example shown in the first method above would appear as 
follows: 

root: procedure options (main); 

declare ?ovlay entry (char (10), fixed (1)); 

declare dummy entry (char (15)); 

declare name char (10) ; 

put skip list ('root') ; 

name = 'OVl' ; 

call ?ovlay (name, 0) ; 

call dummy ('overlay 1') ; 

end root; 

OV1.PLI would be the same as before. 

At run-time the overlay manager would load OVl.OVL from the 
default drive, since that is the current value of the variable 'name', 
and then return to the calling program (in this case, root) . At this 
point, the argument 'overlay 1' would be set up according to the 
PL/I-80 parameter passing conventions. The 'call dummy' transfers 
control to the overlay manager, which would simply tranfer control to 
the base address of the overlay whose name was just processed. When 
OV1 is finished, it returns to the statement following the 'call 
dummy' statement. Note that while in the example above, 'name' was 
set to 'OV1' in an assignment statement, the overlay name could have 
been supplied as a character string derived from some other source, 
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such as the operator's keyboard. Several important points must be 
observed when using the second overlay technique: 

A drive code may be specified so overlays may be loaded from 
drives other than the default drive. If no drive is specified, 
the default drive is used as described in Method 1. 

Since the name of the overlay is specified in the character 
string (and not by the entry symbol) , it may be up to 8 
characters in length. 

If there are any parameters in the dummy call following the 
'call ?ovlay', they must agree in number and type with the 
parameters in the procedure declaration in the overlay. 



E.1.2. SPECIFYING OVERLAYS IN THE COMMAND LINE 

The syntax for specifying overlays is similar to that for 
linking without overlays, except that each overlay specification is 
enclosed in parentheses. An overlay specification may be in one of 
the following forms: 

link root(ovl) 

link root (ovl,part2,part3) 

link root (ovl=partl,part2,part3) 

The first command produces the file 0V1.0VL from a file 0V1.REL, 
while the second command produces the 0V1.0VL file from 0V1.REL, 
PART2.REL, and PART3.REL. In the last case, the 0V1.0VL file is 
produced from PARTI. RLE, PART2.REL, and PART3.REL. 

Note that a left parenthesis, which indicates the start of a new 
overlay specification, also indicates the end of the group preceding 
it. In other words, the following command line is invalid and will be 
flagged as an error: 

LINK ROOT(OVl) ,M0RER00T 

All files to be included at any point on the 'tree' must appear 
together, without any intervening overlay specifications. Thus the 
following command is valid: 

LINK R00T,M0RER00T(0V1) 

Any filename in the command line may be followed by a number of 
link switches enclosed in square brackets, as described in the LINK-80 
Operator's Guide. Note that the overlay specifications are not set 
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off from the root module or from each other with commas, 
be used to improve readability. 



Spaces may 



Nesting of overlays is indicated in the command line by nesting 
parentheses. The following command line could be used to link the 
overlay system shown on the first page of the overlay description: 

LINK ROOT (0V1) (0V2 (0V5) (0V6) ) (0V3) (0V4) 



E.1.3. SAMPLE LINK EXECUTION 

In the following sample link operation, notice that 0V1 is 
flagged as an undefined symbol. LINK is simply indicating that 0V1 
has not been defined in the current module, so it is assumed to be 
either the name of an overlay or a dummy entry point to an overlay. 
When linking overlays, each entry variable which refers to an overlay 
(by actual name or a dummy entry) will appear as an undefined symbol. 
No symbols other than these actual or dummy overlay entry points 
should be undefined. 



A>LINK ROOT(OVl) 
LINK 1.1 



PLILIB RQST ROOT 


0100 


UNDEFINED SYMBOLS: 




0V1 






ABSOLUTE 


0000 




CODE SIZE 


18BC (0100- 


-19BB) 


DATA SIZE 


02A9 (1A90- 


-1D38) 


COMMON SIZE 


00D4 (19BC- 


-1A8F) 


USE FACTOR 


4E 





/SYSIN/ 1A15 /SYSPRI/ 1A3A 



LINKING OVl.OVL 
PLILIB RQST 



ABSOLUTE 0000 

CODE SIZE 0024 

DATA SIZE 0002 

COMMON SIZE 0000 

USE FACTOR 09 



(1D80-1DA3) 
(1DA4-1DA5) 



MODULE TOP 



1E00 
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A>ROOT 

root 

overlay 1 

End of Execution 

A> 



E.1.4. RUN-TIME ERROR MESSAGES 

The overlay manager may produce one of the following error 
messages: 

ERROR (8) OVERLAY, NO FILE d : filename. OVL 
The indicated file could not be found. 

ERROR (9) OVERLAY, DRIVE d : filename. OVL 

An invalid drive code was passed as a parameter to ?ovlay. 

ERROR (10) OVERLAY, SIZE d: filename. OVL 

The indicated overlay would overwrite the PL/I stack and/or free 

space if it were loaded. 

ERROR (11) OVERLAY, NESTING d: f ilename.OVL 

Loading the indicated overlay would exceed the maximum nesting 

depth. 

ERROR (12) OVERLAY, READ d: f ilename.OVL 

Disk read error during overlay load, probably caused by 

premature EOF. 



E.1.5. OTHER OVERLAY SYSTEMS 

A system of overlays may also be produced which is not a tree 
structure, but rather contains a number of separate overlay areas, as 
shown in the figure below: 
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0V2A 



0V2B 



— overlay area 2 



0V1B 



OV1A 



OV1C 



— overlay area 1 



ROOT 



In such a system, the root module can reference any of the 
overlays. An overlay may reference entry points in the root module or 
the main entry point of any overlay which is not in the same overlay 
area. 

Linking a system of overlays as shown above is done in a number 
of steps. One link must be performed for each overlay area, since the 
address of the top of the overlay area must be supplied to LINK when 
linking the next higher overlay area. For example, the command 

LINK ROOT (0V1A) (0V1B) (0V1C) 

generates the three overlays in overlay area 1, and indicates the top 
address of the module. This address is supplied as the load address 
in the next command: 

LINK ROOT (0V2A[Lmod top]) (0V2B [Lmod top]) 

This command creates the overlays for overlay area 2 at the 
appropriate address. Note that the overlay area which is the highest 
in memory should be linked last, since the module top address is 
always written into the root module at the end of the link. 

At some point after the entire system has been linked, it may be 
desirable to relink only one overlay, which may not be at the top 
overlay area. This may be done using the $0Z switch to prevent 
generation of a root module which would contain an erroneous ?MEMRY 
value. 

It is the responsibility of the programmer to ensure that none 
of the overlays overlap, and that no overlay attempts to reference 
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another overlay in the same overlay area. 



E.1.6. THE LINK-80 n $ n SWITCH 

The "$" switch is used to control the source and destination 
devices under LINK-80. The general form of the switch is: 

$td 

where "t* is a type and "d** is a drive specifier. There are five 
types: 

C - console 

I - intermediate 

L - library 

- object 

S - symbol 

The drive specifier may be a letter in the range "K A thru "P" 
corresponding to one of sixteen logical drives, or one of the 
following special characters: 

X - console 

Y - printer 

Z - byte bucket 

$Cd - Console 

Messages which normally appear at the console may be directed to 
the list device ($CY) or may be suppressed ($CZ) . Once $CY or $CZ has 
been specified, $CX may be used later in the command line to redirect 
console messages to the console device. 

$Id - Intermediate 

Intermediate files generated by LINK are normally placed on the 
default drive. The $1 switch allows the user to specify another drive 
to be used by LINK for intermediate files. 

$Ld - Library 
LINK normally searches on the default drive for library files 
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which are automatically linked because of a request item in a REL 
file. The $L switch instructs LINK to search the specified drive for 
these library files. 

$0d - Object 

LINK normally generates an object file on the same drive as the 
first REL file in the command line, unless an output file with an 
explicit drive is included in the command. The $0 switch instructs 
LINK to place the object file on the drive specified by the character 
following the $0, or to suppress the generation of an object file if 
the character following the $0 is a '?,' . 

$Sd - Symbol 

LINK normally generates a symbol file on the same drive as the 
first REL file in the command line, unless an output file with an 
explicit drive is included in the command. The $S switch instructs 
LINK to place the symbol file on the drive specified by the character 
following the $S, or to suppress the generation of a symbol file if 
the character following the $S is a "Z" . 



'td' character pairs following a *$* must not be separated by 
commas. The entire group of $ switches is set off from any other 
switches by a comma, as shown below: 

LINK PARTI [$SZ,$0D,$LB,Q] ,PART2 

LINK PARTI [$SZ0DLB,Q] ,PART2 

LINK PARTI [$SZ OD LB],PART2[Q] 

The three command lines above are equivalent. 

The $1 switch specifies the drive to be used for intermediate 
files during the entire link operation. The other '$* switches may be 
changed in the command line. The value of a '$' switch will remain in 
effect until it is changed as the command line is processed from left 
to right. This is generally useful only when linking overlays. For 
example: 

LINK ROOT (0V1[$SZCZ]) (0V2) (0V3) (0V4[$SACX]) 

will suppress the SYM files and console output generated when 0V1, 0V2 
and 0V3 are linked. When 0V4 is linked, the SYM file will be placed 
on drive A: and the console output will be sent to the console device. 

The NR and NL switches used in LINK 1.0 to suppress the 
recording and listing of the symbol table are not recognized by LINK 
1.1, since $SZ and $CZ can be used to perform these functions. 
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E.1.7. THE REQUEST ITEM 

Version 1.1 of PL/I-80 uses the request item (a specific bit 
pattern in a REL file) to indicate to LINK that the PLILIB is to be 
searched. This is also how the Microsoft compilers link their 
run-time libraries. When LINK processes a library request, it first 
searches for an IRL file with the specified filename. If there is no 
IRL file, it searches for a REL file of that name. Failing in both 
searches, the error message 

NO FILE: filename. REL 

is produced, and LINK aborts. Libraries requested in this manner will 
appear in the symbol table listed at the console with a value of 
'RQST'. 



E.1.8. COMMAND LINE ERRORS 

The error messages 'FILE NAME ERROR' and 'INVALID SYNTAX' are no 
longer generated. Instead, when a command line error of any kind is 
detected the command tail is echoed up to the point where the error 
occurred, followed by a question mark. For example: 

LINK A, B, C; D 
A, B, C;? 

LINK LONGFILENAME 
LONGFILEN? 



E.1.9. ADDITIONAL LIB-80 FACILITIES 

Modules in a library may be deleted or replaced in a single 
command. The names of the modules to be affected are enclosed in 
angle brackets immediately following the name of the source file 
containing the modules. The following examples demonstrate the use of 
this feature. 

lib newlib=oldlib<modl> 

lib newlib=oldlib<modl=f ilel> 

lib newlib=oldlib<modl=> 

lib newlib=oldlib<modl,mod2=f ile2,mod3=> 

In the first case, a new library NEWLIB.REL is created which is 
the same as OLDLIB.REL except that the module MODI is replaced by the 
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contents of the file M0D1.REL. This form should be used if the name 
of the module being replaced is the same as the filename of the REL 
file replacing the module. 

In the second case, the module MODI is replaced by the contents 
of the file FILE1.REL in the new library NEWLIB.REL. This form is 
used to replace a module when the name of the module is not the same 
as the name of the file which is to replace it. Note that this form 
must be used if the filename has more than 6 characters, since module 
names in the REL file are truncated to 6 characters. 



When the third command is used, 
OLDLIB.REL without the module MODI. 



NEWLIB.REL is created from 



The last command form demonstrates that a number of replace 
and/or delete instructions may be included within the angle brackets. 



E.2.0. MULTI-LINE COMMANDS 



comma 
amper 
comma 
aster 
conti 
enter 
retur 
comma 



a command does not 
may be extended 



If 
nd 
sand (&) 
nd, and 



fit on a single line (126 characters) , the 
by terminating the command line with an 
The ampersand may appear after any character of the 
need not follow a file name. LINK-80 resoonds with an 



isk (*) on the next line. At this point the command line may be 
nued. Any number of lines ending with an ampersand may be 
ed. The last line of the command is terminated with a carriage 
n. Note that XSUB may be used to submit multi-line LINK-80 
nds. 



Example: 



A>link main, iomodl, iomod2, iomod3, iomod4, iomod5,& 

LINK 1.3 

*libl[sl, lib2[sl, lib3[s], lib4& 

*[sl, lastmodfp2000& 

*,d2001 

(. . .symbol table and memory map. . .) 

A> 
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APPENDIX F 
XRF.F 

XREF is an assembly-language cross reference utility that can be 
applied to print (PRN) files produced by MAC or RMAC in order to 
provide a summary of variable usage throughout the program. The 
purpose of this appendix is to provide the information necessary for 
operation of the XREF utility. 



F.1.0. XREF OPERATION 

XREF is normally invoked by issuing the command: 

XREF filename 

where the "filename" refers to two input files prepared using MAC or 
RMAC with assumed (and unspecified) file types of "PRN" and "SYM" and 
one output file with an assumed (and unspecified) file type of "XRF". 
Specifically, XREF reads the file "filename. PRN" line by line, 
attaches a line number prefix to each line and writes each prefixed 
line to the output file "filename. XRF". During this process, each 
line is scanned for any symbols that exist in the file "filename. SYM". 
Upon completion of this copy operation, XREF appends to the file 
"filename. XRF" a cross reference report that lists all the line 
numbers where each symbol in "filename. SYM" appears. In addition, 
each line number reference where the referenced symbol is the first 
token on the line is flagged with a "#" character. Also, the value of 
each symbol, as determined by MAC or RMAC and placed in the symbol 
table file "f ilename.SYM" , is reported for each symbol. 

As an option, the "filename" specification can be prefaced with 
a drive code in the standard CP/M format [d:]. When the drive code is 
specified all the files described above are associated with the 
specified drive. Otherwise, the files are associated with the default 
drive. Another option allows the user to direct the output file 
directly to the "LSTs" device instead of to the file "f ilename.XRF" . 
This option is invoked by adding the string "$p" to the command line 
as follows: 

XREF filename $p 

XREF allocates space for symbols and symbol references 

dynamically during execution. If no memory is available for an 

attempted symbol or symbol reference allocation, an error message is 
issued and XREF is terminated. 
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P. 1.1. XREF ERROR MESSAGES 



No SYM file - This message is issued if the file " filename. SYM" 
is not present on the default or specified drive. 

No PRN file - This message is issued if the file n f ilename.PRN" 
is not present on the default or specified drive. 

Symbol table overflow - This message is issued if no space is 
available for an attempted symbol allocation. 

Invalid SYM file format - This message is issued when an invalid 
"file name. SYM" file is read. Specifically, a line in the SYM 
file not terminated with a CRLF will force this error message. 

Symbol table reference overflow - This message is issued if no 
space is available for an attempted symbol reference allocation. 

n f ilename.XRF" make error - This message is issued if BDOS 
returns an error code after a "f ilename.XRF " make request. This 
error code usually indicates that no directory space exists on 
the default or specified drive. 

"f ilename.XRF" close error - This message is issued if BDOS 
returns an error code after a "f ilename.XRF" close request. 

"f ilename.XRF" write error - This message is issued if BDOS 
returns an error code after a "f ilename.XRF" write request. 
This error code usually indicates that no unallocated data 
blocks are available or no directory space exists on the default 
or specified drive. 
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